From 1de102f96becc08572e56307e6d4f21efce2e113 Mon Sep 17 00:00:00 2001 From: Sina Esmaeili Date: Mon, 10 Aug 2026 13:38:15 -0400 Subject: [PATCH] ci: never publish a documentation build that produced no site Two small guards, complementary to #62 (which fixes why the build currently fails). These address how a failed or empty build reaches the live site. Refuse to deploy a build with no index.html. The GitHub Pages deploy uses force_orphan, so it replaces the entire published tree. The last successful deploy (2026-08-04) published a tree containing only .nojekyll and _sphinx_design_static -- no index.html anywhere -- which is why https://mne.tools/mne-denoise/ currently returns 404 for every page. A build that did not produce index.html and auto_examples/index.html should never be allowed to replace a working site. Add a "*" wildcard to the sphinx-gallery subsection_order. Adding any new examples/ subdirectory that contains .py files currently raises sphinx.errors.ConfigError: The subsection folder '../examples/' was not found in the 'subsection_order' config. and fails the entire documentation build. The wildcard sorts unlisted folders to the end instead. (examples/tutorials and examples/output escape this today only because neither contains a .py file.) Verified with the CI invocation locally, sphinx -b html -W --keep-going: build succeeded, 194 HTML pages, 0 warnings, 36 gallery examples. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01W6GFfnt85ZSjuRaDrETwpU --- .github/workflows/ci.yml | 8 ++++++++ docs/conf.py | 3 +++ 2 files changed, 11 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ae12c331..913a7ff1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -80,6 +80,14 @@ jobs: run: make -C docs html SPHINXOPTS="-W --keep-going" - name: Add .nojekyll to the build run: touch docs/_build/html/.nojekyll + # The deploy below is force_orphan, so it replaces the whole site. Refuse + # to publish a build that did not actually produce one. + - name: Verify the build produced a site + run: | + set -e + test -s docs/_build/html/index.html + test -s docs/_build/html/auto_examples/index.html + echo "$(find docs/_build/html -name '*.html' | wc -l) HTML pages built" - name: Upload documentation artifact uses: actions/upload-artifact@v6 with: diff --git a/docs/conf.py b/docs/conf.py index 9b9aa0bd..a66ab267 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -63,6 +63,9 @@ "../examples/zapline", "../examples/asr", "../examples/spectrum_interpolation", + # Trailing wildcard: a new examples/ subdirectory sorts to the end + # instead of failing the whole docs build with a ConfigError. + "*", ] ), "within_subsection_order": FileNameSortKey,