Generate table of contents for litani(7)

The litani(7) man page now contains a table of contents listing all of
the other man pages, separated by chapter. This eliminates the need to
manually maintain this file and keep it up-to-date with new commands.

This commit fixes awslabs#87.

Author: karkhaz

doc/bin/gen-litani7

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+#
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file is distributed
+# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied. See the License for the specific language governing
+# permissions and limitations under the License.
+
+
+import argparse
+import pathlib
+import re
+
+import jinja2
+
+
+_CHAPTER_DESCRIPTIONS = {
+    "1": "Executable Commands",
+    "5": "File Formats & Conventions",
+    "7": "Miscellaneous",
+}
+
+
+def _get_args():
+    pars = argparse.ArgumentParser()
+    for arg in [{
+            "flags": ["--src"],
+            "required": True,
+            "type": pathlib.Path,
+    }, {
+            "flags": ["--dst"],
+            "required": True,
+            "type": pathlib.Path,
+    }, {
+            "flags": ["--man-dir"],
+            "required": True,
+            "type": pathlib.Path,
+    }]:
+        flags = arg.pop("flags")
+        pars.add_argument(*flags, **arg)
+    return pars.parse_args()
+
+
+def get_metadata(man):
+    pat = re.compile(r"^litani (?P<name>[^\s]+)\s+\-\s+(?P<description>.+)")
+    with open(man) as handle:
+        for line in handle:
+            m = pat.match(line)
+            if m:
+                d = m["description"]
+                description = d[0].lower() + d[1:]
+
+                # scdoc inserts these to avoid line breaks
+                name = re.sub(r"\&", "", m["name"])
+                return {
+                    "name": name,
+                    "description": description,
+                }
+    raise UserWarning(
+        f"Could not extract name and description from manual {man}")
+
+
+def _add_mans(man_dir, mans_by_chapter):
+    for man in man_dir.iterdir():
+        if man.name == "litani.7":
+            continue
+        chapter = man.suffix[-1]
+        mans_by_chapter[chapter].append(get_metadata(man))
+    for _, mans in mans_by_chapter.items():
+        mans.sort(key=(lambda m: m["name"]))
+
+
+def main():
+    args = _get_args()
+    mans_by_chapter = {chapter: [] for chapter in _CHAPTER_DESCRIPTIONS}
+
+    _add_mans(args.man_dir, mans_by_chapter)
+
+    chapters = []
+    for num, mans in mans_by_chapter.items():
+        chapters.append({
+            "name": f"Chapter {num}: {_CHAPTER_DESCRIPTIONS[num]}",
+            "mans": mans
+        })
+    chapters.sort(key=(lambda c: c["name"]))
+
+    env = jinja2.Environment(
+        loader=jinja2.FileSystemLoader(str(args.src.parent)),
+        autoescape=jinja2.select_autoescape(
+            enabled_extensions=("html"),
+            default_for_string=True))
+    templ = env.get_template(args.src.name)
+    page = templ.render(chapters=chapters)
+
+    with open(args.dst, "w") as handle:
+        print(page, file=handle)
+
+
+if __name__ == "__main__":
+    main()

doc/configure

@@ -54,6 +54,14 @@ RULES = [{
                " --template"
                f" { TEMPLATE_DIR / 'voluptuous-man.jinja.scdoc' }"
                " | scdoc > ${out}"
+}, {
+    "name": "gen-litani7",
+    "description": "generating litani(7).scdoc",
+    "command":
+            "${script}"
+            " --dst ${out}"
+            " --src ${src}"
+            f" --man-dir {MAN_DIR}"
 }, {
     "name": "man_to_html",
     "description": "converting ${man-name} HTML",
@@ -81,28 +89,28 @@ RULES = [{
 }]
 
 
-def make_html_unique(man, html_man, html_mans, builds):
-    html_unique = HTML_UNIQUE_DIR / f"{man.stem}.html"
+def make_html_unique(man_name, html_man, html_mans, builds):
+    html_unique = HTML_UNIQUE_DIR / f"{man_name}.html"
     builds.append({
         "inputs": [html_man, BIN_DIR / "uniquify-header-ids"],
         "outputs": [html_unique],
         "rule": "uniquify_header_ids",
         "variables": {
-            "man-name": man.stem,
+            "man-name": man_name,
             "in-file": html_man,
         }
     })
     html_mans.append(html_unique)
 
 
-def man_to_html(man, man_out, builds):
-    html_man = HTML_MAN_SRC_DIR / f"{man.stem}.html"
+def man_to_html(man_name, man_out, builds):
+    html_man = HTML_MAN_SRC_DIR / f"{man_name}.html"
     builds.append({
         "inputs": [man_out],
         "outputs": [html_man],
         "rule": "man_to_html",
         "variables": {
-            "man-name": man.stem,
+            "man-name": man_name,
             "in-file": html_man,
         }
     })
@@ -112,13 +120,14 @@ def man_to_html(man, man_out, builds):
 def convert_man_dir_to_man(
         src_dir, dst_dir, rule, html_mans, builds, extra_inputs=None):
     for man in (src_dir).iterdir():
+        man_name = str(man.name).split(".", 1)[0]
         if man.suffix == ".scdoc":
             with open(man) as fp:
                 line = fp.readline().rstrip()
             index = line[line.find('(')+1:line.find(')')]
-            man_out = dst_dir / f"{man.stem}.{index}"
+            man_out = dst_dir / f"{man_name}.{index}"
         else:
-            man_out = dst_dir / f"{man.stem}.5"
+            man_out = dst_dir / f"{man_name}.5"
         inputs = [man]
         if extra_inputs:
             inputs.extend(extra_inputs)
@@ -127,12 +136,43 @@ def convert_man_dir_to_man(
             "outputs": [man_out],
             "rule": rule,
             "variables": {
-                "man-name": man.stem,
+                "man-name": man_name,
                 "data-path": man.resolve(),
             }
         })
-        html_man = man_to_html(man, man_out, builds)
-        make_html_unique(man, html_man, html_mans, builds)
+        html_man = man_to_html(man_name, man_out, builds)
+        make_html_unique(man_name, html_man, html_mans, builds)
+
+
+def add_litani_7(builds, html_mans):
+    """The litani(7) man page is special because it contains a table of contents
+    of the other pages, so it depends on the others."""
+
+    templ = SRC_DIR / "litani7" / "litani.jinja.scdoc"
+    script = BIN_DIR / "gen-litani7"
+
+    inputs = [b["outputs"][0] for b in builds if str(b["outputs"][0])[-1].isdigit()]
+    inputs.extend([templ, script])
+
+    sc_out = TMP_DIR / "litani.scdoc"
+    man_out = TMP_DIR / "litani.7"
+
+    builds.extend([{
+        "inputs": inputs,
+        "outputs": [sc_out],
+        "rule": "gen-litani7",
+        "variables": {
+            "src": templ,
+            "script": script,
+            "man-dir": MAN_DIR,
+        }
+    }, {
+        "inputs": [sc_out],
+        "outputs": [man_out],
+        "rule": "sc_to_man",
+    }])
+    html_man = man_to_html("litani.7", man_out, builds)
+    make_html_unique("litani.7", html_man, html_mans, builds)
 
 
 def main():
@@ -145,6 +185,8 @@ def main():
         SRC_DIR / "voluptuous-man", MAN_DIR, "voluptuous_to_man", html_mans,
         builds, extra_inputs=[TEMPLATE_DIR / "voluptuous-man.jinja.scdoc"])
 
+    add_litani_7(builds, html_mans)
+
     builds.append({
         "inputs": html_mans + [
             BIN_DIR / "build-html-doc",
@@ -162,6 +204,8 @@ def main():
         for k, v in build.items():
             if isinstance(v, list):
                 build[k] = [str(s) for s in v]
+            elif isinstance(v, dict):
+                build[k] = {ik: str(iv) for ik, iv in v.items()}
         try:
             build["implicit"].append(str(DOC_DIR / "configure"))
         except KeyError:

doc/src/litani7/litani.jinja.scdoc

@@ -55,44 +55,19 @@ running, and use the _run.json_ file during or after the build to gain
 insight into the build outcome.
 
 
-# COMMAND LINE INTERFACE
+# MANUAL PAGES -- TABLE OF CONTENTS
 
-The following is a synopsis of Litani's subcommands:
+The following man pages are available with local installations of Litani, or
+online at _https://awslabs.github.io/aws-build-accumulator/_:
 
-*litani init*
-	Create a new Litani build, allowing you to add jobs and subsequently
-	run them.
+{% for chapter in chapters %}{% if chapter["mans"] %}
 
-*litani add-job*
-	Add a job to the build. A 'job' is a command that will be executed as
-	part of the build, possibly with inputs and outputs that describe its
-	place in the dependency graph, and other attributes.
-
-*litani run-build*
-	Execute all jobs that have been added to the build since the last time
-	you ran *litani init*.
-
-*litani dump-run*
-	Print a JSON representation of the run so far to stdout both while the
-	build is running as well as after it has completed.
-
-*litani print-html-dir*
-	Print the path to a continually-updated HTML report directory
-
-*litani acquire-html-dir*
-	Print the path to a locked HTML report directory
-
-*litani release-html-dir*
-	Unlock a previously-locked HTML report directory
-
-*litani graph*
-	Print the dependency graph of the build in Graphviz format, ready to
-	be rendered into an image using *dot(1)*.
-
-*litani print-capabilities*
-	Print a list of features that this version of Litani supports. This
-	can be used as an alternative to checking the version string.
+## {{ chapter["name"] }}
 
+{% for man in chapter["mans"] %}
+*litani {{ man["name"] }}*: {{ man["description"] }}{% if not loop.last %}++{% endif %}
+{%- endfor -%}
+{% endif %}{% endfor %}
 
 # SEE ALSO