source4/scripting/python/samba/tests/docs.py

   1 # Unix SMB/CIFS implementation.
   2 # Copyright (C) Jelmer Vernooij <jelmer@samba.org> 2007-2012
   3 #
   4 # Tests for documentation.
   5 #
   6 # This program is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 3 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18 #
  19
  20 """Tests for presence of documentation."""
  21
  22 import samba
  23 import samba.tests
  24 from samba.tests import TestSkipped
  25
  26 import errno
  27 import os
  28 import re
  29 import subprocess
  30
  31
  32 class TestCase(samba.tests.TestCase):
  33
  34     def _format_message(self, parameters, message):
  35         parameters = list(parameters)
  36         parameters.sort()
  37         return message + '\n\n    %s' % ('\n    '.join(parameters))
  38
  39
  40 class NoXsltProc(Exception):
  41
  42     def __init__(self):
  43         Exception.__init__(self, "'xsltproc' is not installed")
  44
  45
  46 def get_documented_parameters(sourcedir):
  47     try:
  48         p = subprocess.Popen(
  49             ["xsltproc", "--xinclude", "--param", "smb.context", "ALL", "generate-context.xsl", "parameters.all.xml"],
  50             stderr=subprocess.STDOUT, stdout=subprocess.PIPE, cwd=os.path.join(sourcedir, "docs-xml", "smbdotconf"))
  51     except OSError, e:
  52         if e.errno == errno.ENOENT:
  53             raise NoXsltProc()
  54         raise
  55     out, err = p.communicate()
  56     assert p.returncode == 0, "returncode was %r" % p.returncode
  57     for l in out.splitlines():
  58         m = re.match('<samba:parameter .*?name="([^"]*?)"', l)
  59         if m:
  60             name = m.group(1)
  61             yield name
  62         m = re.match('.*<synonym>(.*)</synonym>.*', l)
  63         if m:
  64             name = m.group(1)
  65             yield name
  66
  67
  68 def get_implementation_parameters(sourcedir):
  69     # Reading entries from source code
  70     f = open(os.path.join(sourcedir, "lib/param/param_table.c"), "r")
  71     try:
  72         # burn through the preceding lines
  73         while True:
  74             l = f.readline()
  75             if l.startswith("static struct parm_struct parm_table"):
  76                 break
  77
  78         for l in f.readlines():
  79             if re.match("^\s*\}\;\s*$", l):
  80                 break
  81             # pull in the param names only
  82             if re.match(".*P_SEPARATOR.*", l):
  83                 continue
  84             m = re.match("\s*\.label\s*=\s*\"(.*)\".*", l)
  85             if not m:
  86                 continue
  87
  88             name = m.group(1)
  89             yield name
  90     finally:
  91         f.close()
  92
  93
  94 class SmbDotConfTests(TestCase):
  95
  96     def test_unknown(self):
  97         topdir = samba.source_tree_topdir()
  98         try:
  99             documented = set(get_documented_parameters(topdir))
 100         except NoXsltProc:
 101             raise TestSkipped("'xsltproc' is missing, unable to load parameters")
 102         parameters = set(get_implementation_parameters(topdir))
 103         # Filter out parametric options, since we can't find them in the parm
 104         # table
 105         documented = set([p for p in documented if not ":" in p])
 106         unknown = documented.difference(parameters)
 107         if len(unknown) > 0:
 108             self.fail(self._format_message(unknown,
 109                 "Parameters that are documented but not in the implementation:"))
 110
 111     def test_undocumented(self):
 112         topdir = samba.source_tree_topdir()
 113         try:
 114             documented = set(get_documented_parameters(topdir))
 115         except NoXsltProc:
 116             raise TestSkipped("'xsltproc' is missing, unable to load parameters")
 117         parameters = set(get_implementation_parameters(topdir))
 118         undocumented = parameters.difference(documented)
 119         if len(undocumented) > 0:
 120             self.fail(self._format_message(undocumented,
 121                 "Parameters that are in the implementation but undocumented:"))