Package logilab :: Package common :: Module sphinxutils
[frames] | no frames]

Source Code for Module logilab.common.sphinxutils

  1  """ 
  2  Sphinx utils: 
  3   
  4  * ModuleGenerator: Generate a file that lists all the modules of a list of 
  5      packages in order to pull all the docstring. 
  6      /!\ This should not be used in a makefile to systematically generate 
  7      sphinx documentation! 
  8   
  9  Typical usage: 
 10  >>> from logilab.common.sphinxutils import ModuleGenerator 
 11  >>> mgen = ModuleGenerator('logilab common', '/home/adim/src/logilab/common') 
 12  >>> mgen.generate('api_logilab_common.rst', exclude_dirs=('test',)) 
 13  """ 
 14   
 15  import os, sys 
 16  import os.path as osp 
 17  import inspect 
 18   
 19  from logilab.common import STD_BLACKLIST 
 20  from logilab.common.shellutils import globfind 
 21  from logilab.common.modutils import load_module_from_file, modpath_from_file 
 22   
23 -def module_members(module):
24 members = [] 25 for name, value in inspect.getmembers(module): 26 if getattr(value, '__module__', None) == module.__name__: 27 members.append( (name, value) ) 28 return sorted(members)
29 30
31 -def class_members(klass):
32 return sorted([name for name in vars(klass) 33 if name not in ('__doc__', '__module__', 34 '__dict__', '__weakref__')])
35
36 -class ModuleGenerator:
37 file_header = """.. -*- coding: utf-8 -*-\n\n%s\n""" 38 module_def = """ 39 :mod:`%s` 40 =======%s 41 42 .. automodule:: %s 43 :members: %s 44 """ 45 class_def = """ 46 47 .. autoclass:: %s 48 :members: %s 49 50 """ 51
52 - def __init__(self, project_title, code_dir):
53 self.title = project_title 54 self.code_dir = osp.abspath(code_dir)
55
56 - def generate(self, dest_file, exclude_dirs=STD_BLACKLIST):
57 """make the module file""" 58 self.fn = open(dest_file, 'w') 59 num = len(self.title) + 6 60 title = "=" * num + "\n %s API\n" % self.title + "=" * num 61 self.fn.write(self.file_header % title) 62 self.gen_modules(exclude_dirs=exclude_dirs) 63 self.fn.close()
64
65 - def gen_modules(self, exclude_dirs):
66 """generate all modules""" 67 for module in self.find_modules(exclude_dirs): 68 modname = module.__name__ 69 classes = [] 70 modmembers = [] 71 for objname, obj in module_members(module): 72 if inspect.isclass(obj): 73 classmembers = class_members(obj) 74 classes.append( (objname, classmembers) ) 75 else: 76 modmembers.append(objname) 77 self.fn.write(self.module_def % (modname, '=' * len(modname), 78 modname, 79 ', '.join(modmembers))) 80 for klass, members in classes: 81 self.fn.write(self.class_def % (klass, ', '.join(members)))
82
83 - def find_modules(self, exclude_dirs):
84 basepath = osp.dirname(self.code_dir) 85 basedir = osp.basename(basepath) + osp.sep 86 if basedir not in sys.path: 87 sys.path.insert(1, basedir) 88 for filepath in globfind(self.code_dir, '*.py', exclude_dirs): 89 if osp.basename(filepath) in ('setup.py', '__pkginfo__.py'): 90 continue 91 try: 92 module = load_module_from_file(filepath) 93 except: # module might be broken or magic 94 dotted_path = modpath_from_file(filepath) 95 module = type('.'.join(dotted_path), (), {}) # mock it 96 yield module
97 98 99 if __name__ == '__main__': 100 # example : 101 title, code_dir, outfile = sys.argv[1:] 102 generator = ModuleGenerator(title, code_dir) 103 # XXX modnames = ['logilab'] 104 generator.make(outfile, ('test', 'tests', 'examples', 105 'data', 'doc', '.hg', 'migration')) 106