Exemple #1
0
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))
Exemple #2
0
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))
Exemple #3
0
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))
Exemple #4
0
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
Exemple #5
0
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