docs: parallelize man page generation with make -j

The man_pages Bazel action invoked 'make bazel-manpages' serially, running
~10,000 pandoc/nroff invocations one at a time (~177s on a 64-core host).

Split the single make call into two phases: 'preprocess' (serial) generates
the md/man*/*.md sources, then 'cat web' fan out pandoc/nroff in parallel with
-j. They cannot share one -j invocation because cat/web read the md files that
preprocess produces and there is no dependency edge forcing preprocess first.
Running 'cat web' as a second invocation also re-parses the Makefile so its
$(wildcard md/man*/*.md) picks up the freshly generated sources.

Regenerating the full doc set drops from ~177s to ~6s (~30x).

Signed-off-by: Matt Liberty <mliberty@precisioninno.com>

Author: maliberty

bazel/man_pages.bzl

@@ -18,7 +18,15 @@ def _man_pages_impl(ctx):
 set -euo pipefail
 CAT_OUT="$PWD/{cat_out}"
 HTML_OUT="$PWD/{html_out}"
-make --no-print-directory -C docs -f Makefile bazel-manpages \\
+# Two phases: 'preprocess' (serial) generates the md/man*/*.md sources, then
+# 'cat web' fan out pandoc/nroff in parallel. They cannot share one -j make
+# invocation: cat/web read the md files preprocess produces, and a parallel
+# build has no dependency edge forcing preprocess to finish first. Running
+# 'cat web' as a second invocation also re-parses the Makefile so its
+# $(wildcard md/man*/*.md) picks up the freshly generated sources.
+make --no-print-directory -C docs -f Makefile preprocess \\
+    CAT_ROOT_DIR="$CAT_OUT" HTML_ROOT_DIR="$HTML_OUT"
+make --no-print-directory -j"$(nproc)" -C docs -f Makefile cat web \\
     CAT_ROOT_DIR="$CAT_OUT" HTML_ROOT_DIR="$HTML_OUT"
 """.format(
         cat_out = cat_dir.path,