Docs site serves a build from 2026-07-07: mike deploys to gh-pages, Pages never rebuilds

[LukasGold]

The documentation site https://opensemanticlab.github.io/osw-python/ serves a build from 2026-07-07. Every page added since then returns 404, and mike's version paths do not exist on the site.

Checked on 2026-09-22:

URL	Status
https://opensemanticlab.github.io/osw-python/	200, the July site
https://opensemanticlab.github.io/osw-python/dev/	200, the July dev section, not mike's dev version
https://opensemanticlab.github.io/osw-python/latest/	404
https://opensemanticlab.github.io/osw-python/versions.json	404
https://opensemanticlab.github.io/osw-python/dev/tools/mcp/	404

Cause

The repository Pages setting and the deployment method disagree.

• GET /repos/OpenSemanticLab/osw-python/pages returns "build_type": "workflow", "source": {"branch": "gh-pages", "path": "/"}, "status": "built".
• With build_type: workflow, a push to gh-pages does not start a pages-build-deployment build. The last build and the last github-pages deployment are both from 2026-07-07T08:45Z, for gh-pages commit 641d919.
• No workflow uploads a Pages artifact. actions/upload-pages-artifact, actions/deploy-pages and actions/configure-pages appear in no file under .github/workflows/.
• The documentation is deployed with mike, which commits to gh-pages:
  

  osw-python/.github/workflows/docs.yml

  Line 41 in d7f0116

  run: uv run mike deploy --push dev

  
  

  osw-python/.github/workflows/on-release-main.yml

  Lines 132 to 133 in d7f0116

  	uv run mike deploy --push --alias-type=copy --update-aliases "$VERSION" latest
  	uv run mike set-default --push latest

• The gh-pages branch is current. Its head commit of 2026-09-22 13:50Z says Deployed efde689 to 2.7.0 with Zensical 0.0.47 and mike 2.2.0+zensical-0.1.0. The tree holds versions.json, latest/, dev/tools/mcp/ and the version directories 2.0.0 to 2.7.0. None of it is served.
• docs.yml states the expected setting in its first lines: "versioned docs on the gh-pages branch; repo setting: Pages source = 'Deploy from a branch: gh-pages'". The repository setting does not match.
  

  osw-python/.github/workflows/docs.yml

  Lines 1 to 2 in d7f0116

  	# Deploys the documentation with mike (versioned docs on the gh-pages
  	# branch; repo setting: Pages source = "Deploy from a branch: gh-pages").

Fix

A repository admin sets Pages to "Deploy from a branch", branch gh-pages, folder /. This is what docs.yml and on-release-main.yml already assume, so no code change is needed. Keeping build_type: workflow and adding an upload and deploy job would duplicate what mike does.

The unversioned files at the root of gh-pages (index.html, tools/, osw/, tutorials/ and others) remain from the deployment before mike. After the switch, mike set-default --push latest decides what the root serves, so those files can be removed in a separate step.

Effect

No documentation URL can be linked from code, help output or a README. #200 points the osw-mcp help text at the file on GitHub instead of the documentation site for this reason.

[LukasGold]

Fixed. The site serves mike's current build again.

What was changed

The repository Pages setting is now build_type: legacy with source
gh-pages /, which is what docs.yml and on-release-main.yml assume.

The setting change alone did not start a build. It needed an explicit
POST /repos/OpenSemanticLab/osw-python/pages/builds. That build succeeded for
gh-pages commit 6464a55. Later pushes by mike now build automatically.

Verification

URL	Before	After
https://opensemanticlab.github.io/osw-python/	200, the July site	200, redirects to latest/
https://opensemanticlab.github.io/osw-python/dev/	200, the July dev section	200, mike's dev version
https://opensemanticlab.github.io/osw-python/latest/	404	200
https://opensemanticlab.github.io/osw-python/versions.json	404	200, lists dev and 2.0.0 to 2.7.1
https://opensemanticlab.github.io/osw-python/dev/tools/mcp/	404	200

Likely origin of the wrong setting

Two commits by Andreas Raeder (raederan) on 2026-07-07, 12 minutes apart:

• 13:40 UTC 22c6326 added
  actions/upload-pages-artifact@v4 and actions/deploy-pages@v4. That design
  requires build_type: workflow.
• 13:52 UTC edd958a removed
  both actions and replaced them with mike. That design requires
  "Deploy from a branch".

The setting was never changed back. This is an inference, not a verified fact:
the Pages setting is not stored in git, and the organization audit log is not
readable through the API. What the data does establish is that branch builds
ran until 2026-07-07T08:45Z and never again, so the mode changed after that
time.

A second defect this exposed

mike serves every page under a version directory. The gh-pages root holds
only a redirect. So unversioned deep links in the repository did not work, and
the table above could not reveal this because none of its URLs is one.

Link	Status
README.md /get-started/, twice	404
README.md /tools/	200, but the 2026-07-07 Sphinx page
CONTRIBUTING.md /dev/	200, but mike's dev version home, not docs/dev.md

The last one is a name collision: mike's version dev and the page
docs/dev.md. The development guide is at /latest/dev/.

Fixed in 7da804e, which
points the four deep links at /latest/.... Root links in pyproject.toml,
CITATION.cff and the README badge stay unversioned, because the root redirect
works. All five documentation URLs remaining in the repository return 200.

Follow-up

Removing the pre-mike Sphinx directories from the gh-pages root is tracked in
#205. It has to wait until
7da804e reaches main.

Not addressed

Nothing detects the Pages setting drifting back to workflow. The failure is
silent: workflow runs stay green, gh-pages stays current, and the Pages API
reports "status": "built". Only a 404 report surfaces it.