circuitpython/tools/gendoc.py

"""
Generate documentation for pyboard API from C files.
"""

import os
import argparse
import re
import markdown

# given a list of (name,regex) pairs, find the first one that matches the given line
def re_match_first(regexs, line):
    for name, regex in regexs:
        match = re.match(regex, line)
        if match:
            return name, match
    return None, None

def makedirs(d):
    if not os.path.isdir(d):
        os.makedirs(d)

class Lexer:
    class LexerError(Exception):
        pass

    class EOF(Exception):
        pass

    class Break(Exception):
        pass

    def __init__(self, file):
        self.filename = file
        with open(file, 'rt') as f:
            line_num = 0
            lines = []
            for line in f:
                line_num += 1
                line = line.strip()
                if line == '///':
                    lines.append((line_num, ''))
                elif line.startswith('/// '):
                    lines.append((line_num, line[4:]))
                elif len(lines) > 0 and lines[-1][1] is not None:
                    lines.append((line_num, None))
        if len(lines) > 0 and lines[-1][1] is not None:
            lines.append((line_num, None))
        self.cur_line = 0
        self.lines = lines

    def opt_break(self):
        if len(self.lines) > 0 and self.lines[0][1] is None:
            self.lines.pop(0)

    def next(self):
        if len(self.lines) == 0:
            raise Lexer.EOF
        else:
            l = self.lines.pop(0)
            self.cur_line = l[0]
            if l[1] is None:
                raise Lexer.Break
            else:
                return l[1]

    def error(self, msg):
        print('({}:{}) {}'.format(self.filename, self.cur_line, msg))
        raise Lexer.LexerError

class MarkdownWriter:
    def __init__(self):
        pass

    def start(self):
        self.lines = []

    def end(self):
        return '\n'.join(self.lines)

    def heading(self, level, text):
        if len(self.lines) > 0:
            self.lines.append('')
        self.lines.append(level * '#' + ' ' + text)
        self.lines.append('')

    def para(self, text):
        if len(self.lines) > 0 and self.lines[-1] != '':
            self.lines.append('')
        if isinstance(text, list):
            self.lines.extend(text)
        elif isinstance(text, str):
            self.lines.append(text)
        else:
            assert False
        self.lines.append('')

    def single_line(self, text):
        self.lines.append(text)

    def module(self, name, short_descr, descr):
        self.heading(1, 'module {}'.format(name))
        self.para(descr)

    def function(self, ctx, name, args, descr):
        proto = '{}.{}{}'.format(ctx, self.name, self.args)
        self.heading(3, '`' + proto + '`')
        self.para(descr)

    def method(self, ctx, name, args, descr):
        if name == '\\constructor':
            proto = '{}{}'.format(ctx, args)
        elif name == '\\call':
            proto = '{}{}'.format(ctx, args)
        else:
            proto = '{}.{}{}'.format(ctx, name, args)
        self.heading(3, '`' + proto + '`')
        self.para(descr)

    def constant(self, ctx, name, descr):
        self.single_line('`{}.{}` - {}'.format(ctx, name, descr))

class ReStructuredTextWriter:
    head_chars = {1:'=', 2:'-', 3:'.'}

    def __init__(self):
        pass

    def start(self):
        self.lines = []

    def end(self):
        return '\n'.join(self.lines)

    def _convert(self, text):
        return text.replace('`', '``').replace('*', '\\*')

    def heading(self, level, text, convert=True):
        if len(self.lines) > 0:
            self.lines.append('')
        if convert:
            text = self._convert(text)
        self.lines.append(text)
        self.lines.append(len(text) * self.head_chars[level])
        self.lines.append('')

    def para(self, text, indent=''):
        if len(self.lines) > 0 and self.lines[-1] != '':
            self.lines.append('')
        if isinstance(text, list):
            for t in text:
                self.lines.append(indent + self._convert(t))
        elif isinstance(text, str):
            self.lines.append(indent + self._convert(text))
        else:
            assert False
        self.lines.append('')

    def single_line(self, text):
        self.lines.append(self._convert(text))

    def module(self, name, short_descr, descr):
        self.heading(1, ':mod:`{}` --- {}'.format(name, self._convert(short_descr)), convert=False)
        self.lines.append('.. module:: {}'.format(name))
        self.lines.append('   :synopsis: {}'.format(short_descr))
        self.para(descr)

    def function(self, ctx, name, args, descr):
        args = self._convert(args)
        self.lines.append('.. function:: ' + name + args)
        self.para(descr, indent='   ')

    def method(self, ctx, name, args, descr):
        args = self._convert(args)
        if name == '\\constructor':
            self.lines.append('.. class:: ' + ctx + args)
        elif name == '\\call':
            self.lines.append('.. method:: ' + ctx + args)
        else:
            self.lines.append('.. method:: ' + ctx + '.' + name + args)
        self.para(descr, indent='   ')

    def constant(self, ctx, name, descr):
        self.lines.append('.. data:: ' + name)
        self.para(descr, indent='   ')

class DocValidateError(Exception):
    pass

class DocItem:
    def __init__(self):
        self.doc = []

    def add_doc(self, lex):
        try:
            while True:
                line = lex.next()
                if len(line) > 0 or len(self.doc) > 0:
                    self.doc.append(line)
        except Lexer.Break:
            pass

    def dump(self, writer):
        writer.para(self.doc)

class DocConstant(DocItem):
    def __init__(self, name, descr):
        super().__init__()
        self.name = name
        self.descr = descr

    def dump(self, ctx, writer):
        writer.constant(ctx, self.name, self.descr)

class DocFunction(DocItem):
    def __init__(self, name, args):
        super().__init__()
        self.name = name
        self.args = args

    def dump(self, ctx, writer):
        writer.function(ctx, self.name, self.args, self.doc)

class DocMethod(DocItem):
    def __init__(self, name, args):
        super().__init__()
        self.name = name
        self.args = args

    def dump(self, ctx, writer):
        writer.method(ctx, self.name, self.args, self.doc)

class DocClass(DocItem):
    def __init__(self, name, descr):
        super().__init__()
        self.name = name
        self.descr = descr
        self.constructors = {}
        self.classmethods = {}
        self.methods = {}
        self.constants = {}

    def process_classmethod(self, lex, d):
        name = d['id']
        if name == '\\constructor':
            dict_ = self.constructors
        else:
            dict_ = self.classmethods
        if name in dict_:
            lex.error("multiple definition of method '{}'".format(name))
        method = dict_[name] = DocMethod(name, d['args'])
        method.add_doc(lex)

    def process_method(self, lex, d):
        name = d['id']
        dict_ = self.methods
        if name in dict_:
            lex.error("multiple definition of method '{}'".format(name))
        method = dict_[name] = DocMethod(name, d['args'])
        method.add_doc(lex)

    def process_constant(self, lex, d):
        name = d['id']
        if name in self.constants:
            lex.error("multiple definition of constant '{}'".format(name))
        self.constants[name] = DocConstant(name, d['descr'])
        lex.opt_break()

    def dump(self, writer):
        writer.heading(1, 'class {}'.format(self.name))
        super().dump(writer)
        if len(self.constructors) > 0:
            writer.heading(2, 'Constructors')
            for f in sorted(self.constructors.values(), key=lambda x:x.name):
                f.dump(self.name, writer)
        if len(self.classmethods) > 0:
            writer.heading(2, 'Class methods')
            for f in sorted(self.classmethods.values(), key=lambda x:x.name):
                f.dump(self.name, writer)
        if len(self.methods) > 0:
            writer.heading(2, 'Methods')
            for f in sorted(self.methods.values(), key=lambda x:x.name):
                f.dump(self.name.lower(), writer)
        if len(self.constants) > 0:
            writer.heading(2, 'Constants')
            for c in sorted(self.constants.values(), key=lambda x:x.name):
                c.dump(self.name, writer)

class DocModule(DocItem):
    def __init__(self, name, descr):
        super().__init__()
        self.name = name
        self.descr = descr
        self.functions = {}
        self.constants = {}
        self.classes = {}
        self.cur_class = None

    def new_file(self):
        self.cur_class = None

    def process_function(self, lex, d):
        name = d['id']
        if name in self.functions:
            lex.error("multiple definition of function '{}'".format(name))
        function = self.functions[name] = DocFunction(name, d['args'])
        function.add_doc(lex)

    #def process_classref(self, lex, d):
    #    name = d['id']
    #    self.classes[name] = name
    #    lex.opt_break()

    def process_class(self, lex, d):
        name = d['id']
        if name in self.classes:
            lex.error("multiple definition of class '{}'".format(name))
        self.cur_class = self.classes[name] = DocClass(name, d['descr'])
        self.cur_class.add_doc(lex)

    def process_classmethod(self, lex, d):
        self.cur_class.process_classmethod(lex, d)

    def process_method(self, lex, d):
        self.cur_class.process_method(lex, d)

    def process_constant(self, lex, d):
        if self.cur_class is None:
            # a module-level constant
            name = d['id']
            if name in self.constants:
                lex.error("multiple definition of constant '{}'".format(name))
            self.constants[name] = DocConstant(name, d['descr'])
            lex.opt_break()
        else:
            # a class-level constant
            self.cur_class.process_constant(lex, d)

    def validate(self):
        if self.descr is None:
            raise DocValidateError('module {} referenced but never defined'.format(self.name))

    def dump(self, writer):
        writer.module(self.name, self.descr, self.doc)
        if self.functions:
            writer.heading(2, 'Functions')
            for f in sorted(self.functions.values(), key=lambda x:x.name):
                f.dump(self.name, writer)
        if self.constants:
            writer.heading(2, 'Constants')
            for c in sorted(self.constants.values(), key=lambda x:x.name):
                c.dump(self.name, writer)
        if self.classes:
            writer.heading(2, 'Classes')
            for c in sorted(self.classes.values(), key=lambda x:x.name):
                writer.para('[`{}.{}`]({}) - {}'.format(self.name, c.name, c.name, c.descr))

    def write_html(self, dir):
        md_writer = MarkdownWriter()
        md_writer.start()
        self.dump(md_writer)
        with open(os.path.join(dir, 'index.html'), 'wt') as f:
            f.write(markdown.markdown(md_writer.end()))
        for c in self.classes.values():
            class_dir = os.path.join(dir, c.name)
            makedirs(class_dir)
            md_writer.start()
            md_writer.para('part of the [{} module](./)'.format(self.name))
            c.dump(md_writer)
            with open(os.path.join(class_dir, 'index.html'), 'wt') as f:
                f.write(markdown.markdown(md_writer.end()))

    def write_rst(self, dir):
        rst_writer = ReStructuredTextWriter()
        rst_writer.start()
        self.dump(rst_writer)
        with open(dir + '/' + self.name + '.rst', 'wt') as f:
            f.write(rst_writer.end())
        for c in self.classes.values():
            rst_writer.start()
            c.dump(rst_writer)
            with open(dir + '/' + self.name + '.' + c.name + '.rst', 'wt') as f:
                f.write(rst_writer.end())

class Doc:
    def __init__(self):
        self.modules = {}
        self.cur_module = None

    def new_file(self):
        self.cur_module = None
        for m in self.modules.values():
            m.new_file()

    def check_module(self, lex):
        if self.cur_module is None:
            lex.error('module not defined')

    def process_module(self, lex, d):
        name = d['id']
        if name not in self.modules:
            self.modules[name] = DocModule(name, None)
        self.cur_module = self.modules[name]
        if self.cur_module.descr is not None:
            lex.error("multiple definition of module '{}'".format(name))
        self.cur_module.descr = d['descr']
        self.cur_module.add_doc(lex)

    def process_moduleref(self, lex, d):
        name = d['id']
        if name not in self.modules:
            self.modules[name] = DocModule(name, None)
        self.cur_module = self.modules[name]
        lex.opt_break()

    def process_class(self, lex, d):
        self.check_module(lex)
        self.cur_module.process_class(lex, d)

    def process_function(self, lex, d):
        self.check_module(lex)
        self.cur_module.process_function(lex, d)

    def process_classmethod(self, lex, d):
        self.check_module(lex)
        self.cur_module.process_classmethod(lex, d)

    def process_method(self, lex, d):
        self.check_module(lex)
        self.cur_module.process_method(lex, d)

    def process_constant(self, lex, d):
        self.check_module(lex)
        self.cur_module.process_constant(lex, d)

    def validate(self):
        for m in self.modules.values():
            m.validate()

    def dump(self, writer):
        writer.heading(1, 'Modules')
        writer.para('These are the Python modules that are implemented.')
        for m in sorted(self.modules.values(), key=lambda x:x.name):
            writer.para('[`{}`]({}/) - {}'.format(m.name, m.name, m.descr))

    def write_html(self, dir):
        md_writer = MarkdownWriter()
        with open(os.path.join(dir, 'module', 'index.html'), 'wt') as f:
            md_writer.start()
            self.dump(md_writer)
            f.write(markdown.markdown(md_writer.end()))
        for m in self.modules.values():
            mod_dir = os.path.join(dir, 'module', m.name)
            makedirs(mod_dir)
            m.write_html(mod_dir)

    def write_rst(self, dir):
        #with open(os.path.join(dir, 'module', 'index.html'), 'wt') as f:
        #    f.write(markdown.markdown(self.dump()))
        for m in self.modules.values():
            m.write_rst(dir)

regex_descr = r'(?P<descr>.*)'

doc_regexs = (
    (Doc.process_module, re.compile(r'\\module (?P<id>[a-z][a-z0-9]*) - ' + regex_descr + r'$')),
    (Doc.process_moduleref, re.compile(r'\\moduleref (?P<id>[a-z]+)$')),
    (Doc.process_function, re.compile(r'\\function (?P<id>[a-z0-9_]+)(?P<args>\(.*\))$')),
    (Doc.process_classmethod, re.compile(r'\\classmethod (?P<id>\\?[a-z0-9_]+)(?P<args>\(.*\))$')),
    (Doc.process_method, re.compile(r'\\method (?P<id>\\?[a-z0-9_]+)(?P<args>\(.*\))$')),
    (Doc.process_constant, re.compile(r'\\constant (?P<id>[A-Za-z0-9_]+) - ' + regex_descr + r'$')),
    #(Doc.process_classref, re.compile(r'\\classref (?P<id>[A-Za-z0-9_]+)$')),
    (Doc.process_class, re.compile(r'\\class (?P<id>[A-Za-z0-9_]+) - ' + regex_descr + r'$')),
)

def process_file(file, doc):
    lex = Lexer(file)
    doc.new_file()
    try:
        try:
            while True:
                line = lex.next()
                fun, match = re_match_first(doc_regexs, line)
                if fun == None:
                    lex.error('unknown line format: {}'.format(line))
                fun(doc, lex, match.groupdict())

        except Lexer.Break:
            lex.error('unexpected break')

        except Lexer.EOF:
            pass

    except Lexer.LexerError:
        return False

    return True

def main():
    cmd_parser = argparse.ArgumentParser(description='Generate documentation for pyboard API from C files.')
    cmd_parser.add_argument('--outdir', metavar='<output dir>', default='gendoc-out', help='ouput directory')
    cmd_parser.add_argument('--format', default='html', help='output format: html or rst')
    cmd_parser.add_argument('files', nargs='+', help='input files')
    args = cmd_parser.parse_args()

    doc = Doc()
    for file in args.files:
        print('processing', file)
        if not process_file(file, doc):
            return
    try:
        doc.validate()
    except DocValidateError as e:
        print(e)

    makedirs(args.outdir)

    if args.format == 'html':
        doc.write_html(args.outdir)
    elif args.format == 'rst':
        doc.write_rst(args.outdir)
    else:
        print('unknown format:', args.format)
        return

    print('written to', args.outdir)

if __name__ == "__main__":
    main()