Auto-generate automatic documentation at document build-time

There's little reason to include the files that would get built and/or rebuilt by Sphinx. Avoids bloated diffs.

Author: asullivan-blze

.github/workflows/sphinx.yml

@@ -9,3 +9,5 @@ __pycache__/
 *.egg-info/
 build/
 dist/
+# Contains files which are automatically generated by the documentation build process.
+docs/source/_autogenerated

.gitignore

@@ -11,8 +11,9 @@ container:
 clean:
 	set -o pipefail
 
-	@echo '[.] Removing built packages ...'
+	@echo '[.] Removing built packages and documentation ...'
 	rm -rf dist/
+	make --directory=./docs/ clean
 
 	@echo '[.] Cleaning __pycache__ directories ...'
 	find . -type d -name '__pycache__' | xargs rm -rf

Makefile

@@ -23,6 +23,7 @@ updates.__ 💥
 <!-- README.md-Table-of-Contents_Before -->
 # Table of Contents
 - [Motivation & Goals](#motivation--goals)
+- [Installation](#installation)
 - [Open-Source License](#open-source-license)
 - [Contributing](#contributing)
 - [Concepts](#concepts)
@@ -32,7 +33,6 @@ updates.__ 💥
     - [Local State](#local-state)
     - [Remote State](#remote-state)
 - [Usage](#usage)
-    - [Installation](#installation)
     - [The `Boardwalkfile.py`](#the-boardwalkfilepy)
 - [Command-line Interface](#environment-variables)
 - [`boardwalkd` Server](#boardwalkd-server)
@@ -223,7 +223,6 @@ Boardwalk.
 
 # Usage
 
-(the-boardwalkfilepy)=
 ## The `Boardwalkfile.py`
 
 Boardwalk is both a python library and command-line tool. The `boardwalk`

README.md

@@ -9,14 +9,28 @@ SOURCEDIR     = source
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
+.PHONY: help Makefile
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-.PHONY: help Makefile
+
+# Define some build targets manually, since we also have the auto-generated documentation to handle
+.PHONY: clean
+clean:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	-rm -r source/_autogenerated
+
+.PHONY: generate_cli_help_page_sources
+generate_cli_help_page_sources:
+	./build_cli_help_pages.sh
+
+.PHONY: html
+html: generate_cli_help_page_sources
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-livehtml:
+livehtml: generate_cli_help_page_sources
 	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -30,6 +30,11 @@ GET_PAGE_NAME() {
     echo '`'"$1"'`'
 }
 
+AUTO_GEN_DIR=source/_autogenerated/cli_helpdocs
+mkdir -p "$AUTO_GEN_DIR"
+mkdir -p "$AUTO_GEN_DIR/boardwalk"
+mkdir -p "$AUTO_GEN_DIR/boardwalkd"
+
 for cmd in "${commands[@]}"; do
     # Define regular expression patterns for 'boardwalk' and 'boardwalkd', so we
     # can sort them into the correct subdirectories. Note that we need to use
@@ -47,8 +52,9 @@ for cmd in "${commands[@]}"; do
         echo "[!] Skipping generation for $cmd; is this a boardwalk or boardwalkd command?"
         continue
     fi
-    FILENAME=./source/cli_helpdocs/$SUBDIR/$(echo "$cmd" | tr ' ' _).md
-    echo "[+] Generating doc page for $FILENAME"
+    FILENAME=$AUTO_GEN_DIR/$SUBDIR/$(echo "$cmd" | tr ' ' _).md
+    echo "[+] Generating doc page for $cmd"
+    touch "$FILENAME"
     {
         echo "# $(GET_PAGE_NAME "$cmd")"
         echo ""