#!/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()