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
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
32 return sorted([name for name in vars(klass)
33 if name not in ('__doc__', '__module__',
34 '__dict__', '__weakref__')])
35
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
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
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
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:
94 dotted_path = modpath_from_file(filepath)
95 module = type('.'.join(dotted_path), (), {})
96 yield module
97
98
99 if __name__ == '__main__':
100
101 title, code_dir, outfile = sys.argv[1:]
102 generator = ModuleGenerator(title, code_dir)
103
104 generator.make(outfile, ('test', 'tests', 'examples',
105 'data', 'doc', '.hg', 'migration'))
106