Fix GitHub log verbosity

.github/workflows/docs.yml

@@ -39,7 +39,7 @@ jobs:
           set -o pipefail
           mkdir -p build-logs
           [[ -e doc ]] && cd doc
-          PYTHONUNBUFFERED=1 ./build_docs -b ${PWD}/_build -c -d --verbose 2>&1 | tee >(sed -E $'s/\x1b\\[[0-9;]*[a-zA-Z]//g' > "${GITHUB_WORKSPACE}/build-logs/build.log")
+          PYTHONUNBUFFERED=1 ./build_docs -b ${PWD}/_build -c -d 2>&1 | tee >(sed -E $'s/\x1b\\[[0-9;]*[a-zA-Z]//g' > "${GITHUB_WORKSPACE}/build-logs/build.log")
         # The tee writes build.log for the PR comment (posted by docs-pr-failure-post-comment.yml); the inner sed strips ANSI color codes that would otherwise render as garbage in the comment.
         # PYTHONUNBUFFERED=1 because otherwise the teed log will be out of order
 

source/index.md

@@ -1,34 +1,6 @@
-This tool wraps the build command to build sphinx-based documentation.
+# doc-builder test documentation
 
-This tool assists with creating the correct documentation build commands
-in cases including:
-- Building the documentation from a container
-- Building versioned documentation, where the documentation builds land
-  in subdirectories named based on the source branch
-
-This tool should be put somewhere in your path. Then it should be run
-from the directory that contains the Makefile for building the
-documentation.
-
-Simple usage is:
-
-    build_docs -b /path/to/doc/build/repo/some/subdirectory [-c] [-d]
-
-    Common additional flags are:
-    -c: Before building, run 'make clean'
-    -d: Use a container to build the documentation
-
-Usage for automatically determining the subdirectory in which to build,
-based on the version indicated by the current branch, is:
-
-    ./build_docs -r /path/to/doc/build/repo [-v DOC_VERSION]
-
-    This will build the documentation in a subdirectory of the doc build
-    repo, where the subdirectory is built from DOC_VERSION. If
-    DOC_VERSION isn't given, it will be determined based on the git
-    branch name in the doc source repository.
-
-    In the above example, documentation will be built in:
-    /path/to/doc/build/repo/versions/DOC_VERSION
-
-    This usage also accepts the optional arguments described above.
+```{toctree}
+markdown.md
+reStructuredText.rst
+```

source/markdown.md

@@ -0,0 +1,34 @@
+# Info (markdown)
+
+This tool wraps the build command to build sphinx-based documentation.
+
+This tool assists with creating the correct documentation build commands in cases including:
+- Building the documentation from a container
+- Building versioned documentation, where the documentation builds land in subdirectories named based on the source branch
+
+This tool should be put somewhere in your path. Then it should be run from the directory that contains the Makefile for building the documentation.
+
+Simple usage is:
+
+```shell
+build_docs -b /path/to/doc/build/repo/some/subdirectory [-c] [-d]
+```
+
+Common additional flags are:
+* `-c`: Before building, run `make clean`
+* `-d`: Use a container to build the documentation
+
+Usage for automatically determining the subdirectory in which to build,
+based on the version indicated by the current branch, is:
+
+```shell
+./build_docs -r /path/to/doc/build/repo [-v DOC_VERSION]
+```
+
+This will build the documentation in a subdirectory of the doc build repo, where the subdirectory is built from DOC_VERSION. If DOC_VERSION isn't given, it will be determined based on the git branch name in the doc source repository. In the above example, documentation will be built in:
+
+```
+/path/to/doc/build/repo/versions/DOC_VERSION
+```
+
+This usage also accepts the optional arguments described above.

source/reStructuredText.rst

@@ -0,0 +1,34 @@
+***********************
+Info (reStructuredText)
+***********************
+
+This tool wraps the build command to build sphinx-based documentation.
+
+This tool assists with creating the correct documentation build commands in cases including:
+
+* Building the documentation from a container
+* Building versioned documentation, where the documentation builds land in subdirectories named based on the source branch
+
+This tool should be put somewhere in your path. Then it should be run
+from the directory that contains the Makefile for building the
+documentation.
+
+Simple usage is::
+
+    build_docs -b /path/to/doc/build/repo/some/subdirectory [-c] [-d]
+
+Common additional flags are:
+
+* ``-c``: Before building, run ``make clean``
+* ``-d``: Use a container to build the documentation
+
+Usage for automatically determining the subdirectory in which to build,
+based on the version indicated by the current branch, is::
+
+    ./build_docs -r /path/to/doc/build/repo [-v DOC_VERSION]
+
+This will build the documentation in a subdirectory of the doc build repo, where the subdirectory is built from DOC_VERSION. If DOC_VERSION isn't given, it will be determined based on the git branch name in the doc source repository. In the above example, documentation will be built in::
+
+    /path/to/doc/build/repo/versions/DOC_VERSION
+
+This usage also accepts the optional arguments described above.