author | Sylvain Thénault <sylvain.thenault@logilab.fr> |
Mon, 25 Oct 2010 17:15:55 +0200 | |
changeset 6637 | 6bbfc628555b |
parent 5470 | fb004819cab4 |
child 6880 | 4be32427b2b9 |
permissions | -rwxr-xr-x |
5470
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
1 |
#!/usr/bin/env python |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
2 |
""" |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
3 |
Parser for Javascript comments. |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
4 |
""" |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
5 |
from __future__ import with_statement |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
6 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
7 |
import sys, os, getopt, re |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
8 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
9 |
def clean_comment(match): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
10 |
comment = match.group() |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
11 |
comment = strip_stars(comment) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
12 |
return comment |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
13 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
14 |
# Rest utilities |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
15 |
def rest_title(title, level, level_markups=['=', '=', '-', '~', '+', '`']): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
16 |
size = len(title) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
17 |
if level == 0: |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
18 |
return '\n'.join((level_markups[level] * size, title, level_markups[0] * size)) + '\n' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
19 |
return '\n'.join(('\n' + title, level_markups[level] * size)) + '\n' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
20 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
21 |
def get_doc_comments(text): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
22 |
""" |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
23 |
Return a list of all documentation comments in the file text. Each |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
24 |
comment is a pair, with the first element being the comment text and |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
25 |
the second element being the line after it, which may be needed to |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
26 |
guess function & arguments. |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
27 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
28 |
>>> get_doc_comments(read_file('examples/module.js'))[0][0][:40] |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
29 |
'/**\n * This is the module documentation.' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
30 |
>>> get_doc_comments(read_file('examples/module.js'))[1][0][7:50] |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
31 |
'This is documentation for the first method.' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
32 |
>>> get_doc_comments(read_file('examples/module.js'))[1][1] |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
33 |
'function the_first_function(arg1, arg2) ' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
34 |
>>> get_doc_comments(read_file('examples/module.js'))[2][0] |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
35 |
'/** This is the documentation for the second function. */' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
36 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
37 |
""" |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
38 |
return [clean_comment(match) for match in re.finditer('/\*\*.*?\*/', |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
39 |
text, re.DOTALL|re.MULTILINE)] |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
40 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
41 |
RE_STARS = re.compile('^\s*?\* ?', re.MULTILINE) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
42 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
43 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
44 |
def strip_stars(doc_comment): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
45 |
""" |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
46 |
Strip leading stars from a doc comment. |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
47 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
48 |
>>> strip_stars('/** This is a comment. */') |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
49 |
'This is a comment.' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
50 |
>>> strip_stars('/**\n * This is a\n * multiline comment. */') |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
51 |
'This is a\n multiline comment.' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
52 |
>>> strip_stars('/** \n\t * This is a\n\t * multiline comment. \n*/') |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
53 |
'This is a\n multiline comment.' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
54 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
55 |
""" |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
56 |
return RE_STARS.sub('', doc_comment[3:-2]).strip() |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
57 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
58 |
def parse_js_files(args=sys.argv): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
59 |
""" |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
60 |
Main command-line invocation. |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
61 |
""" |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
62 |
try: |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
63 |
opts, args = getopt.gnu_getopt(args[1:], 'p:o:h', [ |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
64 |
'jspath=', 'output=', 'help']) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
65 |
opts = dict(opts) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
66 |
except getopt.GetoptError: |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
67 |
usage() |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
68 |
sys.exit(2) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
69 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
70 |
rst_dir = opts.get('--output') or opts.get('-o') |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
71 |
if rst_dir is None and len(args) != 1: |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
72 |
rst_dir = 'apidocs' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
73 |
js_dir = opts.get('--jspath') or opts.get('-p') |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
74 |
if not os.path.exists(os.path.join(rst_dir)): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
75 |
os.makedirs(os.path.join(rst_dir)) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
76 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
77 |
f_index = open(os.path.join(rst_dir, 'index.rst'), 'wb') |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
78 |
f_index.write(''' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
79 |
.. toctree:: |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
80 |
:maxdepth: 1 |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
81 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
82 |
''' |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
83 |
) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
84 |
for js_path, js_dirs, js_files in os.walk(js_dir): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
85 |
rst_path = re.sub('%s%s*' % (js_dir, os.path.sep), '', js_path) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
86 |
for js_file in js_files: |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
87 |
if not js_file.endswith('.js'): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
88 |
continue |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
89 |
if not os.path.exists(os.path.join(rst_dir, rst_path)): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
90 |
os.makedirs(os.path.join(rst_dir, rst_path)) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
91 |
rst_content = extract_rest(js_path, js_file) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
92 |
filename = os.path.join(rst_path, js_file[:-3]) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
93 |
# add to index |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
94 |
f_index.write(' %s\n' % filename) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
95 |
# save rst file |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
96 |
with open(os.path.join(rst_dir, filename) + '.rst', 'wb') as f_rst: |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
97 |
f_rst.write(rst_content) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
98 |
f_index.close() |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
99 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
100 |
def extract_rest(js_dir, js_file): |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
101 |
js_filepath = os.path.join(js_dir, js_file) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
102 |
filecontent = open(js_filepath, 'U').read() |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
103 |
comments = get_doc_comments(filecontent) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
104 |
rst = rest_title(js_file, 0) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
105 |
rst += '.. module:: %s\n\n' % js_file |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
106 |
rst += '\n\n'.join(comments) |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
107 |
return rst |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
108 |
|
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
109 |
if __name__ == '__main__': |
fb004819cab4
[book] add generated js documentation to cw book
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff
changeset
|
110 |
parse_js_files() |