Publishing the documentation website¶

Sphinx builds this documentation into a static HTML website. GitHub Pages serves that website. They are separate pieces. This repository includes a GitHub Actions workflow to build and publish it without changing NNPD’s runtime, training settings, or application dependencies.

The documentation uses MyST for Markdown, Furo for navigation/search and light/dark presentation, and AutoAPI to generate the Python reference by parsing sources. Building documentation does not run notebooks, sample data, import the application, or require a GPU.

Publish on GitHub¶

Make sure the repository root contains the settings files, docs/, and the hidden .github/workflows/docs.yml. GitHub only runs workflows from that location.
In the repository, open Settings → Pages. Under Build and deployment, set Source to GitHub Actions.
Open Actions → Documentation → Run workflow, choose the branch to publish from, leave Publish the built documentation to GitHub Pages ticked, and start the run. The deployment job and the Pages settings show the actual published URL after success.

Publishing is deliberate: pushing a commit never republishes the website on its own. Rebuilding and publishing is always the manual Run workflow step above. See What the workflow does for the triggers.

No repository name or account name is hard-coded. The usual project-site address has the form:

https://<owner>.github.io/<repository>/

A repository named <owner>.github.io uses the account-site root instead. Pages availability depends on repository visibility and your GitHub plan. Repository or organization policies can also restrict Actions and deployments. A repository administrator must allow the required actions and Pages environment.

Note

No deployment happens on a push. The workflow needs the repository’s Pages setting and a manual run. A successful local build is not evidence of a live GitHub deployment.

What the workflow does¶

The build job installs only the docs dependency group from uv.lock, not NNPD or PyTorch. It validates documentation sources, builds HTML with Sphinx warnings treated as errors, and checks links and fragment targets in the generated HTML. It runs on three triggers, but only one of them can publish:

Trigger	Builds	Publishes
Run workflow (manual dispatch), `deploy` ticked	yes	yes
Run workflow (manual dispatch), `deploy` unticked	yes	no — build check only
Push to `main`	yes	no
Pull request	yes	no

Pushes and pull requests exist to catch a broken documentation build early. They never deploy and never receive Pages write permissions. Untick deploy on a manual run to rehearse a publish without changing the live site.

The separate deployment job runs only for a manual dispatch that asked to deploy. It has the required pages: write and id-token: write permissions and uses the github-pages environment. No personal access token is needed by the workflow. Because the branch is chosen at dispatch time, the website can be published from a branch other than main when that is what you want.

The workflow uploads only the built HTML directory, not arbitrary training outputs. The website deliberately contains the documentation, the downloadable notebooks, and the paper PDF. Review documentation content before publishing; a private code repository does not by itself imply a private website.

Build and preview locally¶

From the repository root, with uv installed, add the docs dependency group to the environment:

uv sync --group docs
source .venv/bin/activate
python docs/check.py
python -m sphinx -b html -W --keep-going -E -a docs docs/_build/html
python docs/check.py --html docs/_build/html
python -m http.server 8000 --bind 127.0.0.1 --directory docs/_build/html

On Windows PowerShell, activate with .venv\Scripts\Activate.ps1 instead. Open http://127.0.0.1:8000/ in a browser and stop the server with Ctrl+C. The entry page is docs/_build/html/index.html; using the local server also exercises search and assets under normal HTTP. Generated pages are ignored by docs/.gitignore and should not be committed. A later plain uv sync removes the documentation tools from .venv again.

The documentation build itself needs only the docs group. The workflow installs nothing else, with uv sync --locked --only-group docs; do not run that in your experiment environment, because it removes NNPD and PyTorch from it. The API reference reads source files using AutoAPI rather than importing NNPD or downloading PyTorch. A build can be repeated offline once its documentation dependencies have been installed. Package installation itself requires package-index access.

Edit documentation without changing the application¶

File or directory	Purpose
`DOCUMENTATION.md`	Short repository-root entry point for website setup.
`docs/index.md`	Landing page and navigation tree.
`docs/guide/`	Task-oriented usage guides.
`docs/reference/`	Settings, CLI, and API entry pages.
`docs/EXTENDING.md`, `STORAGE.md`, `SCIENTIFIC_NOTES.md`	Detailed extension, storage, and scientific guides.
`docs/conf.py`	Sphinx/MyST/AutoAPI/Furo configuration; documentation only.
`docs` group in `pyproject.toml`	Documentation dependencies, pinned in `uv.lock`.
`docs/_static/nnpd.css`	Small responsive presentation overrides; no font files.
`docs/check.py`	Documentation-source and generated-HTML checks.
`.github/workflows/docs.yml`	Build and Pages deployment automation.

Add a new Markdown page to a toctree in docs/index.md or an existing section. Use normal relative links between pages. Auto-generated API pages come from nnpd/ and gaussian/; do not edit the temporary docs/autoapi/ directory. The displayed settings and extension examples use literalinclude, so they stay tied to their source files without duplicated hand-maintained code.

There are no analytics, external fonts, or required CDN scripts. Site navigation, search, and the generated reference use bundled static assets and relative paths.

Official documentation for the website tooling¶

These external sources describe the website tools, not NNPD’s scientific implementation:

See Testing and validation for the documentation checks and the application test suite.