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:

.. code-block:: powershell

   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.