You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
123 lines
4.3 KiB
Python
123 lines
4.3 KiB
Python
# copyright 2003-2011 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
|
|
# contact http://www.logilab.fr/ -- mailto:contact@logilab.fr
|
|
#
|
|
# This file is part of logilab-common.
|
|
#
|
|
# logilab-common is free software: you can redistribute it and/or modify it under
|
|
# the terms of the GNU Lesser General Public License as published by the Free
|
|
# Software Foundation, either version 2.1 of the License, or (at your option) any
|
|
# later version.
|
|
#
|
|
# logilab-common is distributed in the hope that it will be useful, but WITHOUT
|
|
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
|
|
# details.
|
|
#
|
|
# You should have received a copy of the GNU Lesser General Public License along
|
|
# with logilab-common. If not, see <http://www.gnu.org/licenses/>.
|
|
"""Sphinx utils
|
|
|
|
ModuleGenerator: Generate a file that lists all the modules of a list of
|
|
packages in order to pull all the docstring.
|
|
This should not be used in a makefile to systematically generate sphinx
|
|
documentation!
|
|
|
|
Typical usage:
|
|
|
|
>>> from logilab.common.sphinxutils import ModuleGenerator
|
|
>>> mgen = ModuleGenerator('logilab common', '/home/adim/src/logilab/common')
|
|
>>> mgen.generate('api_logilab_common.rst', exclude_dirs=('test',))
|
|
"""
|
|
|
|
import os, sys
|
|
import os.path as osp
|
|
import inspect
|
|
|
|
from logilab.common import STD_BLACKLIST
|
|
from logilab.common.shellutils import globfind
|
|
from logilab.common.modutils import load_module_from_file, modpath_from_file
|
|
|
|
def module_members(module):
|
|
members = []
|
|
for name, value in inspect.getmembers(module):
|
|
if getattr(value, '__module__', None) == module.__name__:
|
|
members.append( (name, value) )
|
|
return sorted(members)
|
|
|
|
|
|
def class_members(klass):
|
|
return sorted([name for name in vars(klass)
|
|
if name not in ('__doc__', '__module__',
|
|
'__dict__', '__weakref__')])
|
|
|
|
class ModuleGenerator:
|
|
file_header = """.. -*- coding: utf-8 -*-\n\n%s\n"""
|
|
module_def = """
|
|
:mod:`%s`
|
|
=======%s
|
|
|
|
.. automodule:: %s
|
|
:members: %s
|
|
"""
|
|
class_def = """
|
|
|
|
.. autoclass:: %s
|
|
:members: %s
|
|
|
|
"""
|
|
|
|
def __init__(self, project_title, code_dir):
|
|
self.title = project_title
|
|
self.code_dir = osp.abspath(code_dir)
|
|
|
|
def generate(self, dest_file, exclude_dirs=STD_BLACKLIST):
|
|
"""make the module file"""
|
|
self.fn = open(dest_file, 'w')
|
|
num = len(self.title) + 6
|
|
title = "=" * num + "\n %s API\n" % self.title + "=" * num
|
|
self.fn.write(self.file_header % title)
|
|
self.gen_modules(exclude_dirs=exclude_dirs)
|
|
self.fn.close()
|
|
|
|
def gen_modules(self, exclude_dirs):
|
|
"""generate all modules"""
|
|
for module in self.find_modules(exclude_dirs):
|
|
modname = module.__name__
|
|
classes = []
|
|
modmembers = []
|
|
for objname, obj in module_members(module):
|
|
if inspect.isclass(obj):
|
|
classmembers = class_members(obj)
|
|
classes.append( (objname, classmembers) )
|
|
else:
|
|
modmembers.append(objname)
|
|
self.fn.write(self.module_def % (modname, '=' * len(modname),
|
|
modname,
|
|
', '.join(modmembers)))
|
|
for klass, members in classes:
|
|
self.fn.write(self.class_def % (klass, ', '.join(members)))
|
|
|
|
def find_modules(self, exclude_dirs):
|
|
basepath = osp.dirname(self.code_dir)
|
|
basedir = osp.basename(basepath) + osp.sep
|
|
if basedir not in sys.path:
|
|
sys.path.insert(1, basedir)
|
|
for filepath in globfind(self.code_dir, '*.py', exclude_dirs):
|
|
if osp.basename(filepath) in ('setup.py', '__pkginfo__.py'):
|
|
continue
|
|
try:
|
|
module = load_module_from_file(filepath)
|
|
except: # module might be broken or magic
|
|
dotted_path = modpath_from_file(filepath)
|
|
module = type('.'.join(dotted_path), (), {}) # mock it
|
|
yield module
|
|
|
|
|
|
if __name__ == '__main__':
|
|
# example :
|
|
title, code_dir, outfile = sys.argv[1:]
|
|
generator = ModuleGenerator(title, code_dir)
|
|
# XXX modnames = ['logilab']
|
|
generator.generate(outfile, ('test', 'tests', 'examples',
|
|
'data', 'doc', '.hg', 'migration'))
|