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 == 'Cura.util.pymclevel':
  17                 return
  18         if dirname == 'Cura.util.Power':
  19                 return
  20         if dirname == 'Cura.plugins':
  21                 return
  22         if dirname == 'Cura.resouces':
  23                 return
  24         for moduleName in filter(lambda f: f.endswith('.py'), fnames):
  25                 moduleName = moduleName[:-3]
  26                 if moduleName == '__init__':
  27                         continue
  28                 fullName = '%s.%s' % (dirname, moduleName)
  29                 try:
  30                         module = __import__(fullName, fromlist=['Cura'], level=1)
  31                         moduleList.append(module)
  32                 except:
  33                         #traceback.print_exc()
  34                         print "Failed to load: %s" % (fullName)
  35
  36 def main():
  37         """
  38         Main doctest function.
  39         Calculate how many things are documented and not documented yet.
  40         And report a random selection of undocumented functions/ modules.
  41         """
  42         moduleList = []
  43         os.path.walk("Cura", treeWalk, moduleList)
  44         moduleDocCount = 0
  45         functionCount = 0
  46         functionDocCount = 0
  47         typeCount = 0
  48         typeDocCount = 0
  49         undocList = []
  50         for module in moduleList:
  51                 if inspect.getdoc(module):
  52                         moduleDocCount += 1
  53                 else:
  54                         undocList.append(module.__name__)
  55                 for name in dir(module):
  56                         a = getattr(module, name)
  57                         try:
  58                                 if not inspect.getfile(a).startswith('Cura'):
  59                                         continue
  60                         except:
  61                                 continue
  62                         if type(a) is types.FunctionType:
  63                                 functionCount += 1
  64                                 if inspect.getdoc(a):
  65                                         functionDocCount += 1
  66                                 # else:
  67                                 #       undocList.append('%s.%s' % (module.__name__, name))
  68                         elif type(a) is types.TypeType:
  69                                 typeCount += 1
  70                                 if inspect.getdoc(a):
  71                                         typeDocCount += 1
  72                                 # else:
  73                                 #       undocList.append('%s.%s' % (module.__name__, name))
  74                                 for name2 in dir(a):
  75                                         a2 = getattr(a, name2)
  76                                         if type(a2) is types.MethodType:
  77                                                 if hasattr(a.__bases__[0], name2):
  78                                                         continue
  79                                                 functionCount += 1
  80                                                 if inspect.getdoc(a2):
  81                                                         functionDocCount += 1
  82                                                 # else:
  83                                                 #       undocList.append('%s.%s.%s' % (module.__name__, name, name2))
  84
  85         print '%d/%d modules have documentation.' % (moduleDocCount, len(moduleList))
  86         print '%d/%d functions have documentation.' % (functionDocCount, functionCount)
  87         print '%d/%d types have documentation.' % (typeDocCount, typeCount)
  88         print '%.1f%% documented.' % (float(moduleDocCount + functionDocCount + typeDocCount) / float(len(moduleList) + functionCount + typeCount) * 100.0)
  89         print ''
  90         print 'You might want to document:'
  91         for n in xrange(0, 10):
  92                 print random.Random().choice(undocList)
  93
  94 if __name__ == '__main__':
  95         main()