Cura/doctest.py

   1 """
   2 A helper file to check which parts of the code have documentation and which are lacking documentation.
   3 This because much of the Cura code is currently undocumented which needs to be improved.
   4 """
   5 import os
   6 import traceback
   7 import glob
   8 import sys
   9 import inspect
  10 import types
  11 import random
  12
  13 def treeWalk(moduleList, dirname, fnames):
  14         """ Callback from the os.path.walk function, see if the given path is a module and import it to put it in the moduleList """
  15         dirname = dirname.replace("\\", ".").replace("/", ".")
  16         if dirname.startswith('Cura.gui'):
  17                 return
  18         if dirname == 'Cura.util.pymclevel':
  19                 return
  20         if dirname == 'Cura.util.Power':
  21                 return
  22         if dirname == 'Cura.plugins':
  23                 return
  24         if dirname == 'Cura.resouces':
  25                 return
  26         for moduleName in filter(lambda f: f.endswith('.py'), fnames):
  27                 moduleName = moduleName[:-3]
  28                 if moduleName == '__init__':
  29                         continue
  30                 fullName = '%s.%s' % (dirname, moduleName)
  31                 try:
  32                         module = __import__(fullName, fromlist=['Cura'], level=1)
  33                         moduleList.append(module)
  34                 except:
  35                         #traceback.print_exc()
  36                         print "Failed to load: %s" % (fullName)
  37
  38 def main():
  39         """
  40         Main doctest function.
  41         Calculate how many things are documented and not documented yet.
  42         And report a random selection of undocumented functions/ modules.
  43         """
  44         moduleList = []
  45         os.path.walk("Cura", treeWalk, moduleList)
  46         moduleDocCount = 0
  47         functionCount = 0
  48         functionDocCount = 0
  49         memberCount = 0
  50         memberDocCount = 0
  51         typeCount = 0
  52         typeDocCount = 0
  53         undocList = []
  54         for module in moduleList:
  55                 if inspect.getdoc(module):
  56                         moduleDocCount += 1
  57                 else:
  58                         undocList.append(module.__name__)
  59                 for name in dir(module):
  60                         a = getattr(module, name)
  61                         try:
  62                                 if not inspect.getfile(a).startswith('Cura'):
  63                                         continue
  64                         except:
  65                                 continue
  66                         if type(a) is types.FunctionType:
  67                                 functionCount += 1
  68                                 if inspect.getdoc(a):
  69                                         functionDocCount += 1
  70                                 else:
  71                                         undocList.append('%s.%s' % (module.__name__, name))
  72                         elif type(a) is types.TypeType:
  73                                 typeCount += 1
  74                                 if inspect.getdoc(a):
  75                                         typeDocCount += 1
  76                                 else:
  77                                         undocList.append('%s.%s' % (module.__name__, name))
  78                                 for name2 in dir(a):
  79                                         a2 = getattr(a, name2)
  80                                         if type(a2) is types.MethodType:
  81                                                 if hasattr(a.__bases__[0], name2):
  82                                                         continue
  83                                                 memberCount += 1
  84                                                 if inspect.getdoc(a2):
  85                                                         memberDocCount += 1
  86                                                 # else:
  87                                                 #       undocList.append('%s.%s.%s' % (module.__name__, name, name2))
  88
  89         print '%d/%d modules have documentation.' % (moduleDocCount, len(moduleList))
  90         print '%d/%d types have documentation.' % (typeDocCount, typeCount)
  91         print '%d/%d functions have documentation.' % (functionDocCount, functionCount)
  92         print '%d/%d member functions have documentation.' % (memberDocCount, memberCount)
  93         print '%.1f%% documented.' % (float(moduleDocCount + functionDocCount + typeDocCount + memberDocCount) / float(len(moduleList) + functionCount + typeCount + memberCount) * 100.0)
  94         print ''
  95         print 'You might want to document:'
  96         for n in xrange(0, 10):
  97                 print random.Random().choice(undocList)
  98
  99 if __name__ == '__main__':
 100         main()