From f77196d87cd8466057eb54fdcd957ca928857434 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 11:51:57 -0600 Subject: [PATCH 1/4] Improve test docs. * Add reStructuredText version * Fix formatting in both --- source/index.md | 38 +++++-------------------------------- source/markdown.md | 34 +++++++++++++++++++++++++++++++++ source/reStructuredText.rst | 34 +++++++++++++++++++++++++++++++++ 3 files changed, 73 insertions(+), 33 deletions(-) create mode 100644 source/markdown.md create mode 100644 source/reStructuredText.rst diff --git a/source/index.md b/source/index.md index 559a48b..08d3f6d 100644 --- a/source/index.md +++ b/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 +``` \ No newline at end of file diff --git a/source/markdown.md b/source/markdown.md new file mode 100644 index 0000000..a68fd54 --- /dev/null +++ b/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. diff --git a/source/reStructuredText.rst b/source/reStructuredText.rst new file mode 100644 index 0000000..c1204a4 --- /dev/null +++ b/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. From 293fabb72d5f0457f79d6c6eef16ebf05000e045 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 11:52:57 -0600 Subject: [PATCH 2/4] Add intentional rST error --- source/reStructuredText.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reStructuredText.rst b/source/reStructuredText.rst index c1204a4..7215109 100644 --- a/source/reStructuredText.rst +++ b/source/reStructuredText.rst @@ -1,6 +1,6 @@ *********************** Info (reStructuredText) -*********************** +******************* This tool wraps the build command to build sphinx-based documentation. From 38249ab4814ad2baafa0a40001ef5149fddec316 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 12:02:25 -0600 Subject: [PATCH 3/4] docs.yml: No verbose. --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b2d0168..66aaa72 100644 --- a/.github/workflows/docs.yml +++ b/.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 From 1ff3df892a193fbcd71984363658ad2bbd9b3c99 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 12:03:23 -0600 Subject: [PATCH 4/4] Revert "Add intentional rST error" This reverts commit 293fabb72d5f0457f79d6c6eef16ebf05000e045. --- source/reStructuredText.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reStructuredText.rst b/source/reStructuredText.rst index 7215109..c1204a4 100644 --- a/source/reStructuredText.rst +++ b/source/reStructuredText.rst @@ -1,6 +1,6 @@ *********************** Info (reStructuredText) -******************* +*********************** This tool wraps the build command to build sphinx-based documentation.