doc/tools/pyjsrest.py
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Fri, 17 Sep 2010 16:54:56 +0200
branchstable
changeset 6282 556b1b1a2c5a
parent 5470 fb004819cab4
child 6880 4be32427b2b9
permissions -rwxr-xr-x
[reledit] new rtag entry to control apparition of relation label in default value
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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()