Restructure documentation site publishing

[bwstefano]

Summary

• replace the previous site/ sync workflow with a MkDocs workflow that validates documentation builds on pull requests
• publish generated documentation to the dedicated gh-pages branch when documentation changes reach master
• remove the generated site/ tree from the main development branch and ignore local MkDocs build output
• preserve the custom jeowp.org GitHub Pages domain through docs/CNAME

Context

This addresses #518 by separating documentation source from the generated publishing artifact. The previous workflow committed the generated MkDocs output back into the main branch, which kept site/ synchronized but also mixed generated HTML with normal development history.

The new flow keeps docs/, mkdocs.yml, and requirements-docs.txt as the source of truth. Pull requests validate that MkDocs still builds, while deployment writes the generated site to gh-pages, which is already the configured GitHub Pages source for the repository.

Implementation details

• .github/workflows/docs-site.yml now has separate build and deploy jobs.
• The build job runs on pull requests to develop or master, plus relevant pushes/manual runs.
• The deploy job only runs when the ref is master, including manual dispatches from master, and publishes with mkdocs gh-deploy --force --clean --remote-branch gh-pages.
• site/ is removed from version control and added to .gitignore as a local build output.
• docs/CNAME ensures a clean gh-pages deploy keeps the jeowp.org custom domain.
• site_url now matches the configured GitHub Pages custom domain.

Validation

• python3 -m mkdocs build --clean --strict
• python3 -m mkdocs gh-deploy --help to confirm the workflow options are available
• Ruby YAML parse check for .github/workflows/docs-site.yml
• git diff --cached --check

Follow-up

This PR intentionally does not redesign or translate the documentation site. It only fixes the publishing architecture so future editorial and visual work can happen without generated HTML living in the main development branch.

Closes #518

[leopiccionia]

This is a very useful PR, as docs, in practice, are not currently generated in master and CI is red: the existing action generates commits at master, but this is a protected branch for direct commits (what makes docs generation fail).

[leopiccionia]

This PR should not be merged as-is anymore, due to new docs workflow in feature/experimental branch. Running this pipeline would revert changes (remove landing page, unmerged new docs pages, etc.).

I'd accept a new PR targeting feature/experimental (to be changed to develop and then master once merged). The new workflow is:

• Compile site-novo and move result to root of gh-pages branch
• Move MkDocs compiled assets to docs folder of same branch
• Maintain .nojekyll and CNAME, as their as critical to GitHub Pages working correctly

[bwstefano]

@leopiccionia, I updated this PR to align it with the current feature/experimental docs publishing flow.

In the commit 988757d, I retargeted the PR to feature/experimental and replaced the old workflow that committed generated site/ output back to the source branch. The workflow now validates MkDocs on pull requests, optionally builds the site-novo/www landing page when that source exists, and deploys to gh-pages from master. During deploys, it keeps the landing page at the root of gh-pages, publishes MkDocs under /docs, and preserves .nojekyll and CNAME.

In the commit 9370943, I also removed the generated documentation output from the source branch itself. MkDocs now builds into the ignored .build/mkdocs directory, and the workflow publishes that generated output to gh-pages/docs. I also added both /.build/ and /site/ to .gitignore so local builds do not accidentally reintroduce compiled HTML.

So the intended separation is now:

• source branches keep documentation sources only;
• gh-pages remains the only branch with generated HTML;
• the landing page root, .nojekyll, and CNAME are preserved during deploys;
• MkDocs output is published under /docs.

The documentation workflow is passing after these changes.

I’ll remove the 3.0 milestone from this PR, since this should stay with the documentation work currently being developed.