def make_overview(module, cmdline_tools):
cmdline_links = find_cmdline_links(module.name, module.path, cmdline_tools)
pickle.dump(cmdline_links,
open(os.path.join("build_info",
"IMP_%s.pck" % module.name), 'wb'), -1)
rmd = tools.open_utf8(os.path.join(module.path, "README.md"), "r").read()
tools.rewrite(
os.path.join("doxygen", "generated", "IMP_%s.dox" % module.name),
"""/** \\namespace %s
\\tableofcontents
%s
*/
""" % ('IMP' if module.name == 'kernel' else 'IMP::' + module.name, rmd))
def make_overview(options, cmdline_tools):
docdir = os.path.join(options.source, "modules", options.name)
cmdline_links = find_cmdline_links(options.name, docdir, cmdline_tools)
pickle.dump(cmdline_links,
open(os.path.join("data", "build_info",
"IMP_%s.pck" % options.name), 'wb'), -1)
rmd = tools.open_utf8(os.path.join(options.source, "modules", options.name,
"README.md"), "r").read()
tools.rewrite(
os.path.join("doxygen", "generated", "IMP_%s.dox" % options.name),
"""/** \\namespace %s
\\tableofcontents
%s
*/
""" % ('IMP' if options.name == 'kernel' else 'IMP::' + options.name, rmd))
def make_overview(options, cmdline_tools):
docdir = os.path.join(options.source, "modules", options.name)
cmdline_links = find_cmdline_links(options.name, docdir, cmdline_tools)
pickle.dump(cmdline_links,
open(os.path.join("data", "build_info",
"IMP_%s.pck" % options.name), 'wb'), -1)
rmd = tools.open_utf8(os.path.join(options.source, "modules", options.name,
"README.md"), "r").read()
tools.rewrite(
os.path.join("doxygen", "generated", "IMP_%s.dox" % options.name),
"""/** \\namespace %s
\\tableofcontents
%s
*/
""" % ('IMP' if options.name == 'kernel' else 'IMP::' + options.name, rmd))
def find_cmdline_links(mod, docdir, cmdline_tools):
"""Look for (sub)sections in the .dox or .md docs for each cmdline tool,
and return a mapping from tool name to (doxygen link, brief desc, num)"""
links = dict.fromkeys(cmdline_tools)
num = 0
todo = {}
docre = re.compile(r'\\(subsection|section|page)\s+(\S+)\s+(\S+):\s*(.*)$')
docre_sep = re.compile(r'\\(subsection|section|page)\s+(\S+)\s+(\S+)\s*$')
mdre = re.compile('#*\s*(\S+):\s*([^#]+)#*\s*{#(\S+)}')
mdre_sep = re.compile('#*\s*(\S+)\s*#*\s*{#(\S+)}')
for g in [os.path.join(docdir, "README.md")] \
+ glob.glob(os.path.join(docdir, "doc", "*.dox")) \
+ glob.glob(os.path.join(docdir, "doc", "*.md")):
for line in tools.open_utf8(g):
if todo and len(line.rstrip('\r\n ')) > 0 \
and line[0] not in " =-\\":
(k, v) = todo.popitem()
links[k] = (v, line.rstrip('\r\n '), num)
num += 1
todo = {}
m = docre.search(line)
if m and m.group(3) in links:
links[m.group(3)] = (m.group(2), m.group(4), num)
num += 1
m = docre_sep.search(line)
if m and m.group(3) in links:
todo = {m.group(3): m.group(2)}
m = mdre.search(line)
if m and m.group(1) in links:
links[m.group(1)] = (m.group(3), m.group(2), num)
num += 1
m = mdre_sep.search(line)
if m and m.group(1) in links:
todo = {m.group(1): m.group(2)}
missing_links = [tool for tool, link in links.items() if link is None]
if missing_links:
print("""
Could not find section title for command line tool %s
in IMP.%s docs.
Each command line tool should have a section or page in the documentation
(in %s/README.md or
%s/doc/*.{dox,md})
that describes it. The section title should contain the tool's name and a
brief description (separated by a colon), followed by a unique doxygen ID.
Alternatively, the brief description can be given in the body immediately
following the title. For example, the tool do_foo.py could be documented with
\section do_foo_bin do_foo.py: Do something with foo
or
\section do_foo_bin do_foo.py
Do something with foo
in doxygen (\subsection or \page can also be used) or
doo_foo.py: Do something with foo {#do_foo_bin}
=================================
or
# doo_foo.py: Do something with foo {#do_foo_bin}
or
# doo_foo.py {#do_foo_bin}
Do something with foo
in Markdown.
""" % (", ".join(missing_links), mod, docdir, docdir))
sys.exit(1)
return links
def find_cmdline_links(mod, docdir, cmdline_tools):
"""Look for (sub)sections in the .dox or .md docs for each cmdline tool,
and return a mapping from tool name to (doxygen link, brief desc, num)"""
links = dict.fromkeys(cmdline_tools)
num = 0
todo = {}
docre = re.compile(r'\\(subsection|section|page)\s+(\S+)\s+(\S+):\s*(.*)$')
docre_sep = re.compile(r'\\(subsection|section|page)\s+(\S+)\s+(\S+)\s*$')
mdre = re.compile('#*\s*(\S+):\s*([^#]+)#*\s*{#(\S+)}')
mdre_sep = re.compile('#*\s*(\S+)\s*#*\s*{#(\S+)}')
for g in [os.path.join(docdir, "README.md")] \
+ glob.glob(os.path.join(docdir, "doc", "*.dox")) \
+ glob.glob(os.path.join(docdir, "doc", "*.md")):
for line in tools.open_utf8(g):
if todo and len(line.rstrip('\r\n ')) > 0 \
and line[0] not in " =-\\":
(k, v) = todo.popitem()
links[k] = (v, line.rstrip('\r\n '), num)
num += 1
todo = {}
m = docre.search(line)
if m and m.group(3) in links:
links[m.group(3)] = (m.group(2), m.group(4), num)
num += 1
m = docre_sep.search(line)
if m and m.group(3) in links:
todo = {m.group(3): m.group(2)}
m = mdre.search(line)
if m and m.group(1) in links:
links[m.group(1)] = (m.group(3), m.group(2), num)
num += 1
m = mdre_sep.search(line)
if m and m.group(1) in links:
todo = {m.group(1): m.group(2)}
missing_links = [tool for tool, link in links.items() if link is None]
if missing_links:
print("""
Could not find section title for command line tool %s
in IMP.%s docs.
Each command line tool should have a section or page in the documentation
(in %s/README.md or
%s/doc/*.{dox,md})
that describes it. The section title should contain the tool's name and a
brief description (separated by a colon), followed by a unique doxygen ID.
Alternatively, the brief description can be given in the body immediately
following the title. For example, the tool do_foo.py could be documented with
\section do_foo_bin do_foo.py: Do something with foo
or
\section do_foo_bin do_foo.py
Do something with foo
in doxygen (\subsection or \page can also be used) or
doo_foo.py: Do something with foo {#do_foo_bin}
=================================
or
# doo_foo.py: Do something with foo {#do_foo_bin}
or
# doo_foo.py {#do_foo_bin}
Do something with foo
in Markdown.
""" % (", ".join(missing_links), mod, docdir, docdir))
sys.exit(1)
return links
