Publishing the documentation

This page is the canonical description of how the Nornir monodoc is built and how it reaches https://nornir.github.io/.

Local build

  1. Use Python 3.13+ (aligned with current nornir-* packages).

  2. Create or activate a virtual environment.

  3. Install Sphinx dependencies and editable packages (from the monorepo root):

    pip install -r docs/requirements.txt
pip install -e nornir-shared
pip install -e nornir-pools
pip install -e nornir-imageregistration
pip install -e nornir-buildmanager

    If dependency resolution pulls remote Git URLs instead of your local trees, install the four packages in that order and adjust pins as needed for your branch.

  4. Build HTML:

    sphinx-build -b html docs docs/_build/html

  5. Open docs/_build/html/index.html in a browser to preview.

Continuous integration

The workflow ``.github/workflows/docs.yml`` in this monorepo:

  • Runs on pushes to main / master (and on pull requests for a build-only check). Manual workflow_dispatch on those branches also builds and deploys.

  • Checks out git submodules (required for editable nornir-* installs).

  • Installs docs/requirements.txt and the same editable packages as above.

  • Runs sphinx-build -b html docs docs/_build/html.

  • On push or workflow_dispatch to the default branch, deploys the contents of docs/_build/html to the external repository ``nornir/nornir.github.io`` on branch ``master`` (the branch GitHub Pages serves; option A: push built HTML).

See the workflow file for the exact triggers and action versions.

Deploy credentials (Option A)

Pushing from this repo into another repository requires a token or deploy key with write access to nornir/nornir.github.io. The workflow uses peaceiris/actions-gh-pages with:

  • Secret (placeholder name): NORNIR_GITHUB_IO_DEPLOY_TOKEN — a fine-grained or classic PAT with contents: write on nornir/nornir.github.io, stored in this monorepo’s Settings → Secrets and variables → Actions.

Without that secret, the HTML build can succeed while Publish to nornir.github.io fails with not found deploy key or tokens.

Version banner

Release lines such as |version| in Sphinx come from the monorepo ``VERSION`` file at the repository root (see docs/conf.py). Update that file when bumping the umbrella release shown in the doc banner.