kopia lustrzana https://github.com/micropython/micropython
tools/gendoc.py: Remove unused script.
This used to be used to generate .rst docs from inline comments in the C code (specifically for APIs) but is now unused. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>pull/9696/head
Jim Mussared
Damien George
rodzic
02ad71468f
commit
1504204606
551
tools/gendoc.py
551
tools/gendoc.py
|
|
@ -1,551 +0,0 @@
|
|||
"""
|
||||
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()
|
||||
Ładowanie…
Reference in New Issue