kopia lustrzana https://github.com/micropython/micropython
tools: Make gendoc.py able to output RST format.
rodzic
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))
|
print('({}:{}) {}'.format(self.filename, self.cur_line, msg))
|
||||||
raise Lexer.LexerError
|
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):
|
class DocValidateError(Exception):
|
||||||
pass
|
pass
|
||||||
|
|
||||||
|
@ -83,8 +199,8 @@ class DocItem:
|
||||||
except Lexer.Break:
|
except Lexer.Break:
|
||||||
pass
|
pass
|
||||||
|
|
||||||
def dump(self):
|
def dump(self, writer):
|
||||||
return '\n'.join(self.doc)
|
writer.para(self.doc)
|
||||||
|
|
||||||
class DocConstant(DocItem):
|
class DocConstant(DocItem):
|
||||||
def __init__(self, name, descr):
|
def __init__(self, name, descr):
|
||||||
|
@ -92,8 +208,8 @@ class DocConstant(DocItem):
|
||||||
self.name = name
|
self.name = name
|
||||||
self.descr = descr
|
self.descr = descr
|
||||||
|
|
||||||
def dump(self, ctx):
|
def dump(self, ctx, writer):
|
||||||
return '`{}.{}` - {}'.format(ctx, self.name, self.descr)
|
writer.constant(ctx, self.name, self.descr)
|
||||||
|
|
||||||
class DocFunction(DocItem):
|
class DocFunction(DocItem):
|
||||||
def __init__(self, name, args):
|
def __init__(self, name, args):
|
||||||
|
@ -101,14 +217,17 @@ class DocFunction(DocItem):
|
||||||
self.name = name
|
self.name = name
|
||||||
self.args = args
|
self.args = args
|
||||||
|
|
||||||
def dump(self, ctx):
|
def dump(self, ctx, writer):
|
||||||
if self.name == '\\constructor':
|
writer.function(ctx, self.name, self.args, self.doc)
|
||||||
s = '### `{}{}`'.format(ctx, self.args)
|
|
||||||
elif self.name == '\\call':
|
class DocMethod(DocItem):
|
||||||
s = '### `{}{}`'.format(ctx, self.args)
|
def __init__(self, name, args):
|
||||||
else:
|
super().__init__()
|
||||||
s = '### `{}.{}{}`'.format(ctx, self.name, self.args)
|
self.name = name
|
||||||
return s + '\n' + super().dump()
|
self.args = args
|
||||||
|
|
||||||
|
def dump(self, ctx, writer):
|
||||||
|
writer.method(ctx, self.name, self.args, self.doc)
|
||||||
|
|
||||||
class DocClass(DocItem):
|
class DocClass(DocItem):
|
||||||
def __init__(self, name, descr):
|
def __init__(self, name, descr):
|
||||||
|
@ -128,7 +247,7 @@ class DocClass(DocItem):
|
||||||
dict_ = self.classmethods
|
dict_ = self.classmethods
|
||||||
if name in dict_:
|
if name in dict_:
|
||||||
lex.error("multiple definition of method '{}'".format(name))
|
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)
|
method.add_doc(lex)
|
||||||
|
|
||||||
def process_method(self, lex, d):
|
def process_method(self, lex, d):
|
||||||
|
@ -136,7 +255,7 @@ class DocClass(DocItem):
|
||||||
dict_ = self.methods
|
dict_ = self.methods
|
||||||
if name in dict_:
|
if name in dict_:
|
||||||
lex.error("multiple definition of method '{}'".format(name))
|
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)
|
method.add_doc(lex)
|
||||||
|
|
||||||
def process_constant(self, lex, d):
|
def process_constant(self, lex, d):
|
||||||
|
@ -146,37 +265,25 @@ class DocClass(DocItem):
|
||||||
self.constants[name] = DocConstant(name, d['descr'])
|
self.constants[name] = DocConstant(name, d['descr'])
|
||||||
lex.opt_break()
|
lex.opt_break()
|
||||||
|
|
||||||
def dump(self):
|
def dump(self, writer):
|
||||||
s = []
|
writer.heading(1, 'class {}'.format(self.name))
|
||||||
s.append('')
|
super().dump(writer)
|
||||||
s.append('# class {}'.format(self.name))
|
|
||||||
s.append('')
|
|
||||||
s.append(super().dump())
|
|
||||||
if len(self.constructors) > 0:
|
if len(self.constructors) > 0:
|
||||||
s.append('')
|
writer.heading(2, 'Constructors')
|
||||||
s.append("## Constructors")
|
|
||||||
for f in sorted(self.constructors.values(), key=lambda x:x.name):
|
for f in sorted(self.constructors.values(), key=lambda x:x.name):
|
||||||
s.append('')
|
f.dump(self.name, writer)
|
||||||
s.append(f.dump(self.name))
|
|
||||||
if len(self.classmethods) > 0:
|
if len(self.classmethods) > 0:
|
||||||
s.append('')
|
writer.heading(2, 'Class methods')
|
||||||
s.append("## Class methods")
|
|
||||||
for f in sorted(self.classmethods.values(), key=lambda x:x.name):
|
for f in sorted(self.classmethods.values(), key=lambda x:x.name):
|
||||||
s.append('')
|
f.dump(self.name, writer)
|
||||||
s.append(f.dump(self.name))
|
|
||||||
if len(self.methods) > 0:
|
if len(self.methods) > 0:
|
||||||
s.append('')
|
writer.heading(2, 'Methods')
|
||||||
s.append("## Methods")
|
|
||||||
for f in sorted(self.methods.values(), key=lambda x:x.name):
|
for f in sorted(self.methods.values(), key=lambda x:x.name):
|
||||||
s.append('')
|
f.dump(self.name.lower(), writer)
|
||||||
s.append(f.dump(self.name.lower()))
|
|
||||||
if len(self.constants) > 0:
|
if len(self.constants) > 0:
|
||||||
s.append('')
|
writer.heading(2, 'Constants')
|
||||||
s.append("## Constants")
|
|
||||||
for c in sorted(self.constants.values(), key=lambda x:x.name):
|
for c in sorted(self.constants.values(), key=lambda x:x.name):
|
||||||
s.append('')
|
c.dump(self.name, writer)
|
||||||
s.append(c.dump(self.name))
|
|
||||||
return '\n'.join(s)
|
|
||||||
|
|
||||||
class DocModule(DocItem):
|
class DocModule(DocItem):
|
||||||
def __init__(self, name, descr):
|
def __init__(self, name, descr):
|
||||||
|
@ -232,43 +339,47 @@ class DocModule(DocItem):
|
||||||
if self.descr is None:
|
if self.descr is None:
|
||||||
raise DocValidateError('module {} referenced but never defined'.format(self.name))
|
raise DocValidateError('module {} referenced but never defined'.format(self.name))
|
||||||
|
|
||||||
def dump(self):
|
def dump(self, writer):
|
||||||
s = []
|
writer.module(self.name, self.descr, self.doc)
|
||||||
s.append('# module {}'.format(self.name))
|
|
||||||
s.append('')
|
|
||||||
s.append(super().dump())
|
|
||||||
if self.functions:
|
if self.functions:
|
||||||
s.append('')
|
writer.heading(2, 'Functions')
|
||||||
s.append('## Functions')
|
|
||||||
for f in sorted(self.functions.values(), key=lambda x:x.name):
|
for f in sorted(self.functions.values(), key=lambda x:x.name):
|
||||||
s.append('')
|
f.dump(self.name, writer)
|
||||||
s.append(f.dump(self.name))
|
|
||||||
if self.constants:
|
if self.constants:
|
||||||
s.append('')
|
writer.heading(2, 'Constants')
|
||||||
s.append("## Constants")
|
|
||||||
for c in sorted(self.constants.values(), key=lambda x:x.name):
|
for c in sorted(self.constants.values(), key=lambda x:x.name):
|
||||||
s.append('')
|
c.dump(self.name, writer)
|
||||||
s.append(c.dump(self.name))
|
|
||||||
if self.classes:
|
if self.classes:
|
||||||
s.append('')
|
writer.heading(2, 'Classes')
|
||||||
s.append('## Classes')
|
|
||||||
for c in sorted(self.classes.values(), key=lambda x:x.name):
|
for c in sorted(self.classes.values(), key=lambda x:x.name):
|
||||||
s.append('')
|
writer.para('[`{}.{}`]({}) - {}'.format(self.name, c.name, c.name, c.descr))
|
||||||
s.append('[`{}.{}`]({}) - {}'.format(self.name, c.name, c.name, c.descr))
|
|
||||||
return '\n'.join(s)
|
|
||||||
|
|
||||||
def write(self, dir):
|
def write_html(self, dir):
|
||||||
index = markdown.markdown(self.dump())
|
md_writer = MarkdownWriter()
|
||||||
|
md_writer.start()
|
||||||
|
self.dump(md_writer)
|
||||||
with open(os.path.join(dir, 'index.html'), 'wt') as f:
|
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():
|
for c in self.classes.values():
|
||||||
class_dir = os.path.join(dir, c.name)
|
class_dir = os.path.join(dir, c.name)
|
||||||
makedirs(class_dir)
|
makedirs(class_dir)
|
||||||
class_dump = c.dump()
|
md_writer.start()
|
||||||
class_dump = 'part of the [{} module](./)'.format(self.name) + '\n' + class_dump
|
md_writer.para('part of the [{} module](./)'.format(self.name))
|
||||||
index = markdown.markdown(class_dump)
|
c.dump(md_writer)
|
||||||
with open(os.path.join(class_dir, 'index.html'), 'wt') as f:
|
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:
|
class Doc:
|
||||||
def __init__(self):
|
def __init__(self):
|
||||||
|
@ -325,24 +436,28 @@ class Doc:
|
||||||
for m in self.modules.values():
|
for m in self.modules.values():
|
||||||
m.validate()
|
m.validate()
|
||||||
|
|
||||||
def dump(self):
|
def dump(self, writer):
|
||||||
s = []
|
writer.heading(1, 'Modules')
|
||||||
s.append('# Modules')
|
writer.para('These are the Python modules that are implemented.')
|
||||||
s.append('')
|
|
||||||
s.append('These are the Python modules that are implemented.')
|
|
||||||
s.append('')
|
|
||||||
for m in sorted(self.modules.values(), key=lambda x:x.name):
|
for m in sorted(self.modules.values(), key=lambda x:x.name):
|
||||||
s.append('')
|
writer.para('[`{}`]({}/) - {}'.format(m.name, m.name, m.descr))
|
||||||
s.append('[`{}`]({}/) - {}'.format(m.name, m.name, m.descr))
|
|
||||||
return '\n'.join(s)
|
|
||||||
|
|
||||||
def write(self, dir):
|
def write_html(self, dir):
|
||||||
|
md_writer = MarkdownWriter()
|
||||||
with open(os.path.join(dir, 'module', 'index.html'), 'wt') as f:
|
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():
|
for m in self.modules.values():
|
||||||
mod_dir = os.path.join(dir, 'module', m.name)
|
mod_dir = os.path.join(dir, 'module', m.name)
|
||||||
makedirs(mod_dir)
|
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>.*)'
|
regex_descr = r'(?P<descr>.*)'
|
||||||
|
|
||||||
|
@ -383,6 +498,7 @@ def process_file(file, doc):
|
||||||
def main():
|
def main():
|
||||||
cmd_parser = argparse.ArgumentParser(description='Generate documentation for pyboard API from C files.')
|
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('--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')
|
cmd_parser.add_argument('files', nargs='+', help='input files')
|
||||||
args = cmd_parser.parse_args()
|
args = cmd_parser.parse_args()
|
||||||
|
|
||||||
|
@ -395,7 +511,17 @@ def main():
|
||||||
doc.validate()
|
doc.validate()
|
||||||
except DocValidateError as e:
|
except DocValidateError as e:
|
||||||
print(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)
|
print('written to', args.outdir)
|
||||||
|
|
||||||
if __name__ == "__main__":
|
if __name__ == "__main__":
|
||||||
|
|
Ładowanie…
Reference in New Issue