Fix build_docs_to_publish again

.github/workflows/docs-to-publish.yml

@@ -0,0 +1,61 @@
+name: Test building docs "to publish" when they're updated
+
+on:
+  push:
+    # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
+    branches: ['*']
+    # When you copy this into your repo, you should uncomment the following 3 lines:
+    # paths:
+    #   - 'doc/doc-builder'
+    #   - 'doc/build_docs_to_publish'
+
+  pull_request:
+    # Run on pull requests that change the listed files
+    # When you copy this into your repo, you should uncomment the following 3 lines:
+    # paths:
+    #   - 'doc/doc-builder'
+    #   - 'doc/build_docs_to_publish'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+jobs:
+
+  test-build-docs-to-publish-container:
+    if: ${{ always() }}
+    name: With container from registry
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          submodules: true
+
+      - name: Build docs using Docker (Podman has trouble on GitHub runners)
+        id: build-docs
+        run: |
+          set -o pipefail
+          mkdir -p build-logs
+          [[ -e doc ]] && cd doc
+          git fetch
+          PYTHONUNBUFFERED=1 ./build_docs_to_publish -r ${PWD}/_build -d --verbose --site-root "$PWD/_publish" 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
+
+      # The rest of the steps only trigger on failure of above build-docs step.
+      # They upload logs that will be used by the docs-pr-failure-post-comment.yml workflow.
+
+      - name: Record PR number on failure
+        if: failure() && steps.build-docs.outcome == 'failure' && github.event_name == 'pull_request'
+        run: |
+          mkdir -p build-logs
+          echo "${{ github.event.pull_request.number }}" > build-logs/pr_number.txt
+
+      - name: Upload logs on failure
+        if: failure() && steps.build-docs.outcome == 'failure'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: test-build-docs-to-publish-container_failed
+          path: build-logs/

.github/workflows/docs.yml

@@ -57,4 +57,4 @@ jobs:
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: test-build-docs-container_failed
-          path: build-logs/
+          path: build-logs/

tools/build_docs_to_publish.py

@@ -101,8 +101,8 @@ def checkout_and_build(version, permanent_files, args):
             continue
 
         # Check out file
-        filename = os.path.basename(filepath)
-        subprocess.check_output(f"git checkout {LATEST_REF} -- {filename}", shell=True)
+        relpath = os.path.relpath(filepath)
+        subprocess.check_output(["git", "checkout", LATEST_REF, "--", relpath])
 
     # Build the docs for this version
     build_args = [
@@ -192,6 +192,7 @@ def main():
     args = parser.parse_args()
     if args.container_cli_tool is None:
         args.container_cli_tool = get_container_cli_tool()
+    args.conf_py_path = os.path.relpath(os.path.abspath(args.conf_py_path))
 
     # Check version list for problems
     check_version_list()