twisted/test/test_doc.py

   1 # Copyright (c) Twisted Matrix Laboratories.
   2 # See LICENSE for details.
   3
   4 import inspect, glob
   5 from os import path
   6
   7 from twisted.trial import unittest
   8 from twisted.python import reflect
   9 from twisted.python.modules import getModule
  10
  11
  12
  13 def errorInFile(f, line=17, name=''):
  14     """
  15     Return a filename formatted so emacs will recognize it as an error point
  16
  17     @param line: Line number in file.  Defaults to 17 because that's about how
  18         long the copyright headers are.
  19     """
  20     return '%s:%d:%s' % (f, line, name)
  21     # return 'File "%s", line %d, in %s' % (f, line, name)
  22
  23
  24 class DocCoverage(unittest.TestCase):
  25     """
  26     Looking for docstrings in all modules and packages.
  27     """
  28     def setUp(self):
  29         self.packageNames = []
  30         for mod in getModule('twisted').walkModules():
  31             if mod.isPackage():
  32                 self.packageNames.append(mod.name)
  33
  34
  35     def testModules(self):
  36         """
  37         Looking for docstrings in all modules.
  38         """
  39         docless = []
  40         for packageName in self.packageNames:
  41             if packageName in ('twisted.test',):
  42                 # because some stuff in here behaves oddly when imported
  43                 continue
  44             try:
  45                 package = reflect.namedModule(packageName)
  46             except ImportError, e:
  47                 # This is testing doc coverage, not importability.
  48                 # (Really, I don't want to deal with the fact that I don't
  49                 #  have pyserial installed.)
  50                 # print e
  51                 pass
  52             else:
  53                 docless.extend(self.modulesInPackage(packageName, package))
  54         self.failIf(docless, "No docstrings in module files:\n"
  55                     "%s" % ('\n'.join(map(errorInFile, docless)),))
  56
  57
  58     def modulesInPackage(self, packageName, package):
  59         docless = []
  60         directory = path.dirname(package.__file__)
  61         for modfile in glob.glob(path.join(directory, '*.py')):
  62             moduleName = inspect.getmodulename(modfile)
  63             if moduleName == '__init__':
  64                 # These are tested by test_packages.
  65                 continue
  66             elif moduleName in ('spelunk_gnome','gtkmanhole'):
  67                 # argh special case pygtk evil argh.  How does epydoc deal
  68                 # with this?
  69                 continue
  70             try:
  71                 module = reflect.namedModule('.'.join([packageName,
  72                                                        moduleName]))
  73             except Exception, e:
  74                 # print moduleName, "misbehaved:", e
  75                 pass
  76             else:
  77                 if not inspect.getdoc(module):
  78                     docless.append(modfile)
  79         return docless
  80
  81
  82     def testPackages(self):
  83         """
  84         Looking for docstrings in all packages.
  85         """
  86         docless = []
  87         for packageName in self.packageNames:
  88             try:
  89                 package = reflect.namedModule(packageName)
  90             except Exception, e:
  91                 # This is testing doc coverage, not importability.
  92                 # (Really, I don't want to deal with the fact that I don't
  93                 #  have pyserial installed.)
  94                 # print e
  95                 pass
  96             else:
  97                 if not inspect.getdoc(package):
  98                     docless.append(package.__file__.replace('.pyc','.py'))
  99         self.failIf(docless, "No docstrings for package files\n"
 100                     "%s" % ('\n'.join(map(errorInFile, docless),)))
 101
 102
 103     # This test takes a while and doesn't come close to passing.  :(
 104     testModules.skip = "Activate me when you feel like writing docstrings, and fixing GTK crashing bugs."