build: Improve Documentation build performance

The documentation build was slow, and often pathologically slow. The root
of the slowness ties back to all the circumstances in which `cargo run`
would be invoked. In the worst cases, `cargo run` would be run for each man
page *and* those `cargo run`'s would rebuild all of StGit.

One change is to capture the StGit version using `cargo metadata` instead
of by running `stg` with `cargo run`. Running `cargo metadata` does not
have a side effect of building `stg` and is thus always fast. Additionally,
the version is now captured as a simply expanded make variable instead of
recursively expanded variable which ensures that `cargo metadata` will only
be run once per make invocation.

A consequence of this change is that man pages now simply reflect the StGit
version as identified in Cargo.toml, without the supplemental git hash when
building from a non-tagged and/or dirty tree.

Another change is to change the dependency chain for how/when the stg-*.txt
asciidoc files are generated. Previously the STG_COMMANDS_TXT variable
would invoke `cargo run completion list commands` each time it was
recursively expanded. The new strategy is to piggyback on doc.dep to ensure
that stg-*.txt are generated, where txt-stamp is the proxy for stg-*.txt.
With this approach, the stg-*.txt files are generated only when necessary
and they are found by make via $(wildcard).

With these updates, the `clean` target no longer triggers `cargo run` and
thus avoids the previous pathology when running `make clean` on an already
clean repo would first build stg.

Fixes: #229

Author: jpgrayson

Documentation/Makefile

@@ -50,15 +50,12 @@ CARGO ?= cargo --locked
 CARGO_OFFLINE = $(CARGO) --offline
 CARGO_RUN = $(CARGO_OFFLINE) --quiet run --profile=$(STG_PROFILE)
 STG_COMMANDS_SRC = $(shell find ../src/cmd -name '*.rs')
-STG_COMMANDS = $(shell $(CARGO_RUN) completion list commands)
-STG_COMMANDS_TXT = $(patsubst %,stg-%.txt,$(STG_COMMANDS))
+STG_COMMANDS_TXT = $(wildcard stg-*.txt)
 
-# STGIT_VERSION = $(shell $(CARGO) --quiet metadata --format-version=1 --no-deps | \
-#                         jq -r '.packages[].version')
-# STGIT_VERSION = $(shell $(CARGO) --quiet metadata --format-version=1 --no-deps | \
-#                         grep -Eo '"version":"[^"]+"' | \
-#                         sed -Ee 's/"version":"([^"]+)"/\1/g')
-STGIT_VERSION = $(shell $(CARGO_RUN) version --short | sed -e 's/stg //g')
+STGIT_VERSION := $(shell $(CARGO) metadata --format-version=1 --no-deps | \
+                         grep -Eo '"version":"[^"]+"' | \
+                         sed -Ee 's/"version":"([^"]+)"/\1/g')
+# STGIT_VERSION := $(shell $(CARGO_RUN) version --short | sed -e 's/stg //g')
 
 MAN1_TXT += stg.txt
 MAN1_TXT += $(STG_COMMANDS_TXT)
@@ -200,7 +197,7 @@ $(DOC_HTML) $(DOC_MAN1): asciidoc.conf
 #
 # Determine "include::" file references in asciidoc files.
 #
-doc.dep : $(DOC_DEP_TXT) build-docdep.perl
+doc.dep : txt-stamp $(DOC_DEP_TXT) build-docdep.perl
 	$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@ $(QUIET_STDERR)
 
 ifneq ($(MAKECMDGOALS),clean)
@@ -223,7 +220,8 @@ clean:
 	$(RM) doc.dep
 	$(RM) manpage-base-url.xsl
 	$(RM) GIT-ASCIIDOCFLAGS
-	$(RM) $(STG_COMMANDS_TXT) command-list.txt
+	$(RM) stg-*.txt
+	$(RM) command-list.txt
 	$(RM) txt-stamp
 
 $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)