1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
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
49 return sorted([name for name in vars(klass)
50 if name not in ('__doc__', '__module__',
51 '__dict__', '__weakref__')])
52
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
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
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
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:
111 dotted_path = modpath_from_file(filepath)
112 module = type('.'.join(dotted_path), (), {})
113 yield module
114
115
116 if __name__ == '__main__':
117
118 title, code_dir, outfile = sys.argv[1:]
119 generator = ModuleGenerator(title, code_dir)
120
121 generator.generate(outfile, ('test', 'tests', 'examples',
122 'data', 'doc', '.hg', 'migration'))
123