|
1 """generate list of modules for sphinx doc""" |
|
2 |
1 import sys |
3 import sys |
2 |
4 |
3 """ |
5 EXCLUDE_DIRS = ('test', 'tests', 'examples', 'data', 'doc', '.hg', 'migration') |
4 Generates the chapter that list all the modules in CubicWeb |
6 if __name__ == '__main__': |
5 in order to pull all the docstring. |
|
6 """ |
|
7 |
7 |
8 class ModuleGenerator: |
8 from logilab.common.sphinxutils import generate_modules_file |
9 HEADER = """.. -*- coding: utf-8 -*- |
|
10 |
9 |
11 ============ |
10 gen = generate_modules_file(sys.argv[1:]) |
12 CubicWeb API |
11 gen.set_docdir("cubicweb/doc/book/en") |
13 ============ |
12 gen.make(['cubicweb', '/indexer', '/logilab', '/rql', '/yams'], EXCLUDE_DIRS) |
14 """ |
|
15 EXCLUDE_DIRS = ('test', 'tests', 'examples', 'data', 'doc', '.hg', 'migration') |
|
16 |
|
17 def __init__(self, output_fn, mod_names): |
|
18 self.mod_names = mod_names |
|
19 self.fn = open(output_fn, 'w') |
|
20 self.fn.write(self.HEADER) |
|
21 |
|
22 def done(self): |
|
23 self.fn.close() |
|
24 |
|
25 def gen_module(self, mod_name): |
|
26 mod_entry = """ |
|
27 :mod:`%s` |
|
28 %s |
|
29 |
|
30 .. automodule:: %s |
|
31 :members: |
|
32 """ % (mod_name, '='*(len(':mod:``'+mod_name)), mod_name) |
|
33 self.fn.write(mod_entry) |
|
34 |
|
35 def find_modules(self): |
|
36 import os |
|
37 modules = [] |
|
38 for mod_name in self.mod_names: |
|
39 for root, dirs, files in os.walk(mod_name): |
|
40 if self.keep_module(root): |
|
41 for name in files: |
|
42 if name == "__init__.py": |
|
43 if self.format_mod_name(root, mod_name) not in modules: |
|
44 modules.append(self.format_mod_name(root, mod_name)) |
|
45 else: |
|
46 if name.endswith(".py") and name != "__pkginfo__.py" and "__init__.py" in files: |
|
47 filename = root + '/' + name.split('.py')[0] |
|
48 if self.format_mod_name(filename, mod_name) not in modules: |
|
49 modules.append(self.format_mod_name(filename, mod_name)) |
|
50 return modules |
|
51 |
|
52 def gen_modules(self): |
|
53 for module in self.find_modules(): |
|
54 self.gen_module(module) |
|
55 |
|
56 def format_mod_name(self, path, mod_name): |
|
57 mod_root = mod_name.split('/')[-1] |
|
58 mod_end = path.split(mod_root)[-1] |
|
59 return mod_root + mod_end.replace('/', '.') |
|
60 |
|
61 def keep_module(self, mod_end): |
|
62 """ |
|
63 Filter modules in order to exclude specific package directories. |
|
64 """ |
|
65 for dir in self.EXCLUDE_DIRS: |
|
66 if mod_end.find(dir) != -1: |
|
67 return False |
|
68 return True |
|
69 |
|
70 USAGE = """ |
|
71 Two arguments required: |
|
72 generate_modules [cubicweb-root] [file-out] |
|
73 |
|
74 [cubicweb-root] : full path to cubicweb forest |
|
75 [file-out] : rest file containing the list of modules for Sphinx |
|
76 """ |
|
77 def generate_modules_file(args): |
|
78 if len(args) != 2: |
|
79 print USAGE |
|
80 sys.exit() |
|
81 CW_ROOT = args[0] |
|
82 OUTPUT = args[1] |
|
83 modules = (CW_ROOT + '/cubicweb', \ |
|
84 CW_ROOT + '/indexer', \ |
|
85 CW_ROOT + '/logilab', \ |
|
86 CW_ROOT + '/rql', \ |
|
87 CW_ROOT + '/yams') |
|
88 |
|
89 mg = ModuleGenerator(CW_ROOT + '/cubicweb/doc/book/en/' + OUTPUT, modules) |
|
90 mg.find_modules() |
|
91 mg.gen_modules() |
|
92 mg.done() |
|
93 print args |
|
94 |
|
95 |
|
96 |
|
97 if __name__ == '__main__': |
|
98 generate_modules_file(sys.argv[1:]) |
|
99 |
|