Restore command help reference.

.gitignore

@@ -14,7 +14,7 @@ doc/*
 !doc/joss-paper
 
 # derived files
-src/appendices/command-ref.rst
+src/reference/command-help.rst
 
 # editor stuff
 *.swp

Makefile

@@ -21,6 +21,7 @@ clean:
 	# remove auto-generated content
 	rm -rf src/plugins/main-loop/built-in
 	rm -rf src/user-guide/task-implementation/job-runner-handlers
+	rm -rf src/reference/command-help.rst
 
 cleanall:
 	(cd doc; echo [0-9]*.*)
@@ -32,6 +33,8 @@ cleanall:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 # NOTE: EXPORT_ALL_VARIABLES exports make vars as env vars
 %: Makefile .EXPORT_ALL_VARIABLES
+	# generate command help transcripts
+	bin/autodoc-cli
 	# build documentation
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	# write out dict of available versions and formats

bin/autodoc-cli

@@ -15,66 +15,30 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-# Create appendices/command-ref.rst for inclusion in HTML doc.
+# Create command help transcripts for inclusion in HTML doc.
 
 # All paths relative to 'doc/src/custom/' directory:
-COMMAND_REF_FILE="$(dirname "$0")/../src/appendices/command-ref.rst"
-CYLC="cylc"
+COMMAND_REF_FILE="$(dirname "$0")/../src/reference/command-help.rst"
 
 cat > "$COMMAND_REF_FILE" <<END
 .. _CommandReference:
 
 Command Reference
 =================
 
-.. _help:
-
-Help
-----
-
-.. code-block:: none
-
-   $("${CYLC}" --help | awk '{print "   " $0}')
-
-Command Categories
-------------------
-
-END
-
-for CAT in $($CYLC categories); do
-	cat >> "$COMMAND_REF_FILE" <<END
-
-.. _command-cat-${CAT}:
-
-${CAT}
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
-   $("$CYLC" "$CAT" --help | awk '{print "   " $0}')
-
-END
-
-done
-
-cat >> "$COMMAND_REF_FILE" <<END
-
-Commands
---------
-
 END
 
-for COM in $($CYLC commands); do
+for COM in $(cylc help all | awk '{print $1}' | sort); do
 	cat >> "$COMMAND_REF_FILE" <<END
 
 .. _command-${COM}:
 
-${COM}
+cylc ${COM}
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: none
 
-   $("$CYLC" "$COM" --help  | awk '{print "   " $0}')
+   $(cylc "$COM" --color=never --help  | awk '{print "   " $0}')
 
 END
 

src/reference/index.rst

@@ -8,3 +8,4 @@ Reference
    config/index
    api/index
    dev-history-major-changes
+   command-help