Package logilab :: Package common :: Module sphinxutils

[frames] | no frames]

# Source Code for Module logilab.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