GitHub Pages Publication

The canonical publication path for the repository Sphinx portal is GitHub Pages through the repository-owned GitHub Actions workflow:

  • .github/workflows/publish-sphinx-pages.yml

The live public documentation portal is now available at:

  • https://xilab-robotics.github.io/Physics-Informed-Neural-Networks/

The workflow builds the documentation from the canonical site/ tree and publishes the generated HTML from:

  • site/_build/html

  • site/requirements-docs.txt

The local validation command remains:

conda activate standard_ml_codex_env
python -m pip install -r site/requirements-docs.txt
python -m sphinx -W -b html site site/_build/html

Keep the documentation dependency file installed in the active build environment so the local validation path matches the GitHub Pages dependency resolution, including the explicitly aligned requests dependency family.

The GitHub Pages workflow intentionally does not install the full repository training stack. Instead, it installs a documentation-specific dependency subset plus a CPU-only PyTorch wheel so the hosted runner does not exhaust disk space on unnecessary CUDA, OCR, and video-tooling packages.

Repository rule:

  • when approved work adds or materially changes a script, feature, runnable workflow, or documentation entry point, update the affected Sphinx source content under site/ in the same task;

  • rebuild the portal locally;

  • keep the warning-as-error Sphinx build passing before closing the task.

If the repository Pages settings are not already configured, set the source to GitHub Actions after the workflow is available on the default branch.

The canonical active branch is main. Historical branches such as base, test-manual-ml, and test-codex-agent-pinns should remain outside the active Pages publication path.

If deployment still fails after a successful build with an error stating that main is not allowed to deploy to github-pages, the remaining blocker is the GitHub environment configuration rather than the Sphinx build itself. In that case:

  • open Settings -> Environments -> github-pages;

  • inspect the deployment-branch protection rule;

  • allow the main branch to deploy, or remove the overly restrictive branch filter;

  • rerun the Pages workflow after the environment rule is updated.

If a repository ruleset is already active, retarget that ruleset to main and keep Repository Quality Checks as the required status check on the active branch.

The workflow also opts into Node.js 24 for JavaScript-based GitHub Actions so the repository stays aligned with GitHub’s current Actions runtime transition.