tools: Make gendoc.py able to output RST format.

tools/gendoc.py

@@ -67,6 +67,122 @@ class Lexer:
         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
 
@@ -83,8 +199,8 @@ class DocItem:
         except Lexer.Break:
             pass
 
-    def dump(self):
-        return '\n'.join(self.doc)
+    def dump(self, writer):
+        writer.para(self.doc)
 
 class DocConstant(DocItem):
     def __init__(self, name, descr):
@@ -92,8 +208,8 @@ class DocConstant(DocItem):
         self.name = name
         self.descr = descr
 
-    def dump(self, ctx):
-        return '`{}.{}` - {}'.format(ctx, self.name, self.descr)
+    def dump(self, ctx, writer):
+        writer.constant(ctx, self.name, self.descr)
 
 class DocFunction(DocItem):
     def __init__(self, name, args):
@@ -101,14 +217,17 @@ class DocFunction(DocItem):
         self.name = name
         self.args = args
 
-    def dump(self, ctx):
-        if self.name == '\\constructor':
-            s = '### `{}{}`'.format(ctx, self.args)
-        elif self.name == '\\call':
-            s = '### `{}{}`'.format(ctx, self.args)
-        else:
-            s = '### `{}.{}{}`'.format(ctx, self.name, self.args)
-        return s + '\n' + super().dump()
+    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):
@@ -128,7 +247,7 @@ class DocClass(DocItem):
             dict_ = self.classmethods
         if name in dict_:
             lex.error("multiple definition of method '{}'".format(name))
-        method = dict_[name] = DocFunction(name, d['args'])
+        method = dict_[name] = DocMethod(name, d['args'])
         method.add_doc(lex)
 
     def process_method(self, lex, d):
@@ -136,7 +255,7 @@ class DocClass(DocItem):
         dict_ = self.methods
         if name in dict_:
             lex.error("multiple definition of method '{}'".format(name))
-        method = dict_[name] = DocFunction(name, d['args'])
+        method = dict_[name] = DocMethod(name, d['args'])
         method.add_doc(lex)
 
     def process_constant(self, lex, d):
@@ -146,37 +265,25 @@ class DocClass(DocItem):
         self.constants[name] = DocConstant(name, d['descr'])
         lex.opt_break()
 
-    def dump(self):
-        s = []
-        s.append('')
-        s.append('# class {}'.format(self.name))
-        s.append('')
-        s.append(super().dump())
+    def dump(self, writer):
+        writer.heading(1, 'class {}'.format(self.name))
+        super().dump(writer)
         if len(self.constructors) > 0:
-            s.append('')
-            s.append("## Constructors")
+            writer.heading(2, 'Constructors')
             for f in sorted(self.constructors.values(), key=lambda x:x.name):
-                s.append('')
-                s.append(f.dump(self.name))
+                f.dump(self.name, writer)
         if len(self.classmethods) > 0:
-            s.append('')
-            s.append("## Class methods")
+            writer.heading(2, 'Class methods')
             for f in sorted(self.classmethods.values(), key=lambda x:x.name):
-                s.append('')
-                s.append(f.dump(self.name))
+                f.dump(self.name, writer)
         if len(self.methods) > 0:
-            s.append('')
-            s.append("## Methods")
+            writer.heading(2, 'Methods')
             for f in sorted(self.methods.values(), key=lambda x:x.name):
-                s.append('')
-                s.append(f.dump(self.name.lower()))
+                f.dump(self.name.lower(), writer)
         if len(self.constants) > 0:
-            s.append('')
-            s.append("## Constants")
+            writer.heading(2, 'Constants')
             for c in sorted(self.constants.values(), key=lambda x:x.name):
-                s.append('')
-                s.append(c.dump(self.name))
-        return '\n'.join(s)
+                c.dump(self.name, writer)
 
 class DocModule(DocItem):
     def __init__(self, name, descr):
@@ -232,43 +339,47 @@ class DocModule(DocItem):
         if self.descr is None:
             raise DocValidateError('module {} referenced but never defined'.format(self.name))
 
-    def dump(self):
-        s = []
-        s.append('# module {}'.format(self.name))
-        s.append('')
-        s.append(super().dump())
+    def dump(self, writer):
+        writer.module(self.name, self.descr, self.doc)
         if self.functions:
-            s.append('')
-            s.append('## Functions')
+            writer.heading(2, 'Functions')
             for f in sorted(self.functions.values(), key=lambda x:x.name):
-                s.append('')
-                s.append(f.dump(self.name))
+                f.dump(self.name, writer)
         if self.constants:
-            s.append('')
-            s.append("## Constants")
+            writer.heading(2, 'Constants')
             for c in sorted(self.constants.values(), key=lambda x:x.name):
-                s.append('')
-                s.append(c.dump(self.name))
+                c.dump(self.name, writer)
         if self.classes:
-            s.append('')
-            s.append('## Classes')
+            writer.heading(2, 'Classes')
             for c in sorted(self.classes.values(), key=lambda x:x.name):
-                s.append('')
-                s.append('[`{}.{}`]({}) - {}'.format(self.name, c.name, c.name, c.descr))
-        return '\n'.join(s)
+                writer.para('[`{}.{}`]({}) - {}'.format(self.name, c.name, c.name, c.descr))
 
-    def write(self, dir):
-        index = markdown.markdown(self.dump())
+    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(index)
+            f.write(markdown.markdown(md_writer.end()))
         for c in self.classes.values():
             class_dir = os.path.join(dir, c.name)
             makedirs(class_dir)
-            class_dump = c.dump()
-            class_dump = 'part of the [{} module](./)'.format(self.name) + '\n' + class_dump
-            index = markdown.markdown(class_dump)
+            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(index)
+                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):
@@ -325,24 +436,28 @@ class Doc:
         for m in self.modules.values():
             m.validate()
 
-    def dump(self):
-        s = []
-        s.append('# Modules')
-        s.append('')
-        s.append('These are the Python modules that are implemented.')
-        s.append('')
+    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):
-            s.append('')
-            s.append('[`{}`]({}/) - {}'.format(m.name, m.name, m.descr))
-        return '\n'.join(s)
+            writer.para('[`{}`]({}/) - {}'.format(m.name, m.name, m.descr))
 
-    def write(self, dir):
+    def write_html(self, dir):
+        md_writer = MarkdownWriter()
         with open(os.path.join(dir, 'module', 'index.html'), 'wt') as f:
-            f.write(markdown.markdown(self.dump()))
+            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(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>.*)'
 
@@ -383,6 +498,7 @@ def process_file(file, doc):
 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()
 
@@ -395,7 +511,17 @@ def main():
         doc.validate()
     except DocValidateError as e:
         print(e)
-    doc.write(args.outdir)
+
+    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__":