tools: Make gendoc.py able to output RST format.
This commit is contained in:
Damien George
parent
1a8573ed0e
commit
7c4445afe1
276
tools/gendoc.py
276
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__":
|
||||
|
|
|
|||
Loading…
Reference in New Issue