[reledit] new rtag entry to control apparition of relation label in default value
#!/usr/bin/env python
"""
Parser for Javascript comments.
"""
from __future__ import with_statement
import sys, os, getopt, re
def clean_comment(match):
comment = match.group()
comment = strip_stars(comment)
return comment
# Rest utilities
def rest_title(title, level, level_markups=['=', '=', '-', '~', '+', '`']):
size = len(title)
if level == 0:
return '\n'.join((level_markups[level] * size, title, level_markups[0] * size)) + '\n'
return '\n'.join(('\n' + title, level_markups[level] * size)) + '\n'
def get_doc_comments(text):
"""
Return a list of all documentation comments in the file text. Each
comment is a pair, with the first element being the comment text and
the second element being the line after it, which may be needed to
guess function & arguments.
>>> get_doc_comments(read_file('examples/module.js'))[0][0][:40]
'/**\n * This is the module documentation.'
>>> get_doc_comments(read_file('examples/module.js'))[1][0][7:50]
'This is documentation for the first method.'
>>> get_doc_comments(read_file('examples/module.js'))[1][1]
'function the_first_function(arg1, arg2) '
>>> get_doc_comments(read_file('examples/module.js'))[2][0]
'/** This is the documentation for the second function. */'
"""
return [clean_comment(match) for match in re.finditer('/\*\*.*?\*/',
text, re.DOTALL|re.MULTILINE)]
RE_STARS = re.compile('^\s*?\* ?', re.MULTILINE)
def strip_stars(doc_comment):
"""
Strip leading stars from a doc comment.
>>> strip_stars('/** This is a comment. */')
'This is a comment.'
>>> strip_stars('/**\n * This is a\n * multiline comment. */')
'This is a\n multiline comment.'
>>> strip_stars('/** \n\t * This is a\n\t * multiline comment. \n*/')
'This is a\n multiline comment.'
"""
return RE_STARS.sub('', doc_comment[3:-2]).strip()
def parse_js_files(args=sys.argv):
"""
Main command-line invocation.
"""
try:
opts, args = getopt.gnu_getopt(args[1:], 'p:o:h', [
'jspath=', 'output=', 'help'])
opts = dict(opts)
except getopt.GetoptError:
usage()
sys.exit(2)
rst_dir = opts.get('--output') or opts.get('-o')
if rst_dir is None and len(args) != 1:
rst_dir = 'apidocs'
js_dir = opts.get('--jspath') or opts.get('-p')
if not os.path.exists(os.path.join(rst_dir)):
os.makedirs(os.path.join(rst_dir))
f_index = open(os.path.join(rst_dir, 'index.rst'), 'wb')
f_index.write('''
.. toctree::
:maxdepth: 1
'''
)
for js_path, js_dirs, js_files in os.walk(js_dir):
rst_path = re.sub('%s%s*' % (js_dir, os.path.sep), '', js_path)
for js_file in js_files:
if not js_file.endswith('.js'):
continue
if not os.path.exists(os.path.join(rst_dir, rst_path)):
os.makedirs(os.path.join(rst_dir, rst_path))
rst_content = extract_rest(js_path, js_file)
filename = os.path.join(rst_path, js_file[:-3])
# add to index
f_index.write(' %s\n' % filename)
# save rst file
with open(os.path.join(rst_dir, filename) + '.rst', 'wb') as f_rst:
f_rst.write(rst_content)
f_index.close()
def extract_rest(js_dir, js_file):
js_filepath = os.path.join(js_dir, js_file)
filecontent = open(js_filepath, 'U').read()
comments = get_doc_comments(filecontent)
rst = rest_title(js_file, 0)
rst += '.. module:: %s\n\n' % js_file
rst += '\n\n'.join(comments)
return rst
if __name__ == '__main__':
parse_js_files()