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         typeCount = 0
  50         typeDocCount = 0
  51         undocList = []
  52         for module in moduleList:
  53                 if inspect.getdoc(module):
  54                         moduleDocCount += 1
  55                 else:
  56                         undocList.append(module.__name__)
  57                 for name in dir(module):
  58                         a = getattr(module, name)
  59                         try:
  60                                 if not inspect.getfile(a).startswith('Cura'):
  61                                         continue
  62                         except:
  63                                 continue
  64                         if type(a) is types.FunctionType:
  65                                 functionCount += 1
  66                                 if inspect.getdoc(a):
  67                                         functionDocCount += 1
  68                                 # else:
  69                                 #       undocList.append('%s.%s' % (module.__name__, name))
  70                         elif type(a) is types.TypeType:
  71                                 typeCount += 1
  72                                 if inspect.getdoc(a):
  73                                         typeDocCount += 1
  74                                 else:
  75                                         undocList.append('%s.%s' % (module.__name__, name))
  76                                 for name2 in dir(a):
  77                                         a2 = getattr(a, name2)
  78                                         if type(a2) is types.MethodType:
  79                                                 if hasattr(a.__bases__[0], name2):
  80                                                         continue
  81                                                 functionCount += 1
  82                                                 if inspect.getdoc(a2):
  83                                                         functionDocCount += 1
  84                                                 # else:
  85                                                 #       undocList.append('%s.%s.%s' % (module.__name__, name, name2))
  86
  87         print '%d/%d modules have documentation.' % (moduleDocCount, len(moduleList))
  88         print '%d/%d functions have documentation.' % (functionDocCount, functionCount)
  89         print '%d/%d types have documentation.' % (typeDocCount, typeCount)
  90         print '%.1f%% documented.' % (float(moduleDocCount + functionDocCount + typeDocCount) / float(len(moduleList) + functionCount + typeCount) * 100.0)
  91         print ''
  92         print 'You might want to document:'
  93         for n in xrange(0, 10):
  94                 print random.Random().choice(undocList)
  95
  96 if __name__ == '__main__':
  97         main()