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

Source Code for Module common.sphinxutils

  1  # copyright 2003-2011 LOGILAB S.A. (Paris, FRANCE), all rights reserved. 
  2  # contact http://www.logilab.fr/ -- mailto:contact@logilab.fr 
  3  # 
  4  # This file is part of logilab-common. 
  5  # 
  6  # logilab-common is free software: you can redistribute it and/or modify it under 
  7  # the terms of the GNU Lesser General Public License as published by the Free 
  8  # Software Foundation, either version 2.1 of the License, or (at your option) any 
  9  # later version. 
 10  # 
 11  # logilab-common is distributed in the hope that it will be useful, but WITHOUT 
 12  # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
 13  # FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more 
 14  # details. 
 15  # 
 16  # You should have received a copy of the GNU Lesser General Public License along 
 17  # with logilab-common.  If not, see <http://www.gnu.org/licenses/>. 
 18  """Sphinx utils 
 19   
 20  ModuleGenerator: Generate a file that lists all the modules of a list of 
 21  packages in order to pull all the docstring. 
 22  This should not be used in a makefile to systematically generate sphinx 
 23  documentation! 
 24   
 25  Typical usage: 
 26   
 27  >>> from logilab.common.sphinxutils import ModuleGenerator 
 28  >>> mgen = ModuleGenerator('logilab common', '/home/adim/src/logilab/common') 
 29  >>> mgen.generate('api_logilab_common.rst', exclude_dirs=('test',)) 
 30  """ 
 31   
 32  import os, sys 
 33  import os.path as osp 
 34  import inspect 
 35   
 36  from logilab.common import STD_BLACKLIST 
 37  from logilab.common.shellutils import globfind 
 38  from logilab.common.modutils import load_module_from_file, modpath_from_file 
 39   
40 -def module_members(module):
41 members = [] 42 for name, value in inspect.getmembers(module): 43 if getattr(value, '__module__', None) == module.__name__: 44 members.append( (name, value) ) 45 return sorted(members)
46 47
48 -def class_members(klass):
49 return sorted([name for name in vars(klass) 50 if name not in ('__doc__', '__module__', 51 '__dict__', '__weakref__')])
52
53 -class ModuleGenerator:
54 file_header = """.. -*- coding: utf-8 -*-\n\n%s\n""" 55 module_def = """ 56 :mod:`%s` 57 =======%s 58 59 .. automodule:: %s 60 :members: %s 61 """ 62 class_def = """ 63 64 .. autoclass:: %s 65 :members: %s 66 67 """ 68
69 - def __init__(self, project_title, code_dir):
70 self.title = project_title 71 self.code_dir = osp.abspath(code_dir)
72
73 - def generate(self, dest_file, exclude_dirs=STD_BLACKLIST):
74 """make the module file""" 75 self.fn = open(dest_file, 'w') 76 num = len(self.title) + 6 77 title = "=" * num + "\n %s API\n" % self.title + "=" * num 78 self.fn.write(self.file_header % title) 79 self.gen_modules(exclude_dirs=exclude_dirs) 80 self.fn.close()
81
82 - def gen_modules(self, exclude_dirs):
83 """generate all modules""" 84 for module in self.find_modules(exclude_dirs): 85 modname = module.__name__ 86 classes = [] 87 modmembers = [] 88 for objname, obj in module_members(module): 89 if inspect.isclass(obj): 90 classmembers = class_members(obj) 91 classes.append( (objname, classmembers) ) 92 else: 93 modmembers.append(objname) 94 self.fn.write(self.module_def % (modname, '=' * len(modname), 95 modname, 96 ', '.join(modmembers))) 97 for klass, members in classes: 98 self.fn.write(self.class_def % (klass, ', '.join(members)))
99
100 - def find_modules(self, exclude_dirs):
101 basepath = osp.dirname(self.code_dir) 102 basedir = osp.basename(basepath) + osp.sep 103 if basedir not in sys.path: 104 sys.path.insert(1, basedir) 105 for filepath in globfind(self.code_dir, '*.py', exclude_dirs): 106 if osp.basename(filepath) in ('setup.py', '__pkginfo__.py'): 107 continue 108 try: 109 module = load_module_from_file(filepath) 110 except: # module might be broken or magic 111 dotted_path = modpath_from_file(filepath) 112 module = type('.'.join(dotted_path), (), {}) # mock it 113 yield module
114 115 116 if __name__ == '__main__': 117 # example : 118 title, code_dir, outfile = sys.argv[1:] 119 generator = ModuleGenerator(title, code_dir) 120 # XXX modnames = ['logilab'] 121 generator.generate(outfile, ('test', 'tests', 'examples', 122 'data', 'doc', '.hg', 'migration')) 123