Skip to content
Snippets Groups Projects
Commit 7c4445af authored by Damien George's avatar Damien George
Browse files

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

parent 1a8573ed
Branches
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 201 additions and 75 deletions
tools/gendoc.py
+ 201
− 75
View file @ 7c4445af
......@@ -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__":
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment