Skip to content

Deploy the docs with the GitHub Pages actions so the site is current again - #187

Merged
kriboe90 merged 3 commits into
masterfrom
claude/ledsmokeanalysis-docs-outdated-14f9c7
Nov 11, 2026
Merged

kriboe90 merged 3 commits into
masterfrom
claude/ledsmokeanalysis-docs-outdated-14f9c7

Conversation

@kriboe90

Copy link
Copy Markdown
Contributor

Why the site is outdated

https://firedynamics.github.io/LEDSmokeAnalysis/ still serves the build of 19 March 2026 (release 0.10.0). The Pages source of the repository (Settings → Pages) is GitHub Actions (build_type: workflow in the Pages API), but the Docs workflow pushes the built HTML to the gh-pages branch, which Pages only publishes when the source is "Deploy from a branch". The last pages-build-deployment run was on 19 March. Every push to master since, the latest on 10 November, built the docs and pushed a correct 0.13.0 build to gh-pages that was never published.

What changed

  • .github/workflows/build_documentation.yaml: on a push to master, the build job uploads _build/ with actions/upload-pages-artifact@v5, and a new deploy job publishes it with actions/deploy-pages@v5 (environment github-pages, one deployment at a time). Branches and pull requests still only build. The workflow needs contents: read instead of contents: write. checkout and setup-python move to v7, which run on Node 24, so the "Node.js 20 is deprecated" warning goes away. The build job is renamed from docs to build; master has no branch protection or ruleset that requires the old check name.
  • doc/conf.py: the release comes from pyproject.toml instead of the metadata of the installed ledsa, which an editable install keeps from when it was installed (locally it reported 0.10.0 for the 0.13.0 source). Python older than 3.11 has no tomllib and falls back to the metadata.
  • doc/cli_documentation.rst:
    • --s1 → -s1, and --acceptance-test[_debug] → --acceptance_test[_debug].
    • --step_3 and --step_3_fast lacked their closing backticks and ran into the option after them in one literal; they now render separately.
    • --setup PATH needs a path rather than defaulting to ..
    • --color_correction and the --n_cores of the demo were missing.
  • doc/installation.rst: the supported Python versions (3.9 to 3.12) and the steps to install from a clone, as in the README.

Testing

  • sphinx-build -W --keep-going doc _build builds without warnings, and the page title and index page show 0.13.0.
  • Every option in the first column of the CLI tables exists in the argparse parser of ledsa.core.parser_arguments_declaration.
  • The workflow validates against the GitHub workflow schema (check-jsonschema --builtin-schema vendor.github-workflows), and the deploy job matches the usage in the actions/deploy-pages README.
  • The deploy job runs only on a push to master, so merging this PR is its first real run. The github-pages environment already allows master to deploy.

After merging

  • The Docs run on master should end with a deploy job that links to the site, which should then show 0.13.0.
  • Nothing writes to gh-pages any more, so that branch can be deleted.
  • PyPI still has 0.12.0, so pip install ledsa gives an older version than the docs describe until 0.13.0 is released.

🤖 Generated with Claude Code

kriboe90 and others added 3 commits November 11, 2026 00:54
The Pages source of the repository is "GitHub Actions", so pushing the built HTML to the gh-pages
branch does not publish it: the site has stayed at the build of 19 March 2026 (0.10.0), while every
push to master since has still built the docs and pushed them to gh-pages. On a push to master the
workflow now uploads the built HTML with actions/upload-pages-artifact and deploys it with
actions/deploy-pages; the github-pages environment already lets master deploy. The build needs only
read access now, and checkout and setup-python move to versions that run on Node 24, which the
runners force on the Node 20 actions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
conf.py took the release from the metadata of the installed ledsa, which an editable install keeps
from the time it was installed: a local build showed 0.10.0 for the 0.13.0 source. It now reads the
pyproject.toml of the source tree it documents, and falls back to the installed metadata on Python
older than 3.11, which lacks tomllib.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The CLI page named -s1 as --s1 and the acceptance test options --acceptance-test instead of
--acceptance_test, and two literals that lacked a backtick rendered as one, "--step_3`,
``--analyse_photo". --setup needs a path rather than defaulting to ".", and --color_correction and
the --n_cores of the demo were missing. Every option the page names now exists in the parser. The
installation page gets the supported Python versions and the steps to install from a clone, as in
the README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kriboe90
kriboe90 merged commit efc0891 into master Nov 11, 2026
7 checks passed
@kriboe90
kriboe90 deleted the claude/ledsmokeanalysis-docs-outdated-14f9c7 branch November 11, 2026 00:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant