Contributing to the documentation¶
Build locally¶
From the repository root, build WavePort and install the locked documentation dependencies:
uv sync --locked --group docs
uv run --no-sync sphinx-build -M html docs docs/_build -W --keep-going -E
Open docs/_build/html/index.html in a browser. The package, including its
native extension, must be importable because the API reference pages in
docs/reference/ extract the docstrings with sphinx.ext.autodoc. When you
add a class or function to the public API, list it with an autoclass or
autofunction directive in the appropriate page. The -E flag makes
Sphinx re-read every page: without it, docstrings defined in src/main.cpp
are not refreshed after rebuilding the extension, because Sphinx cannot track
changes in compiled modules.
Convenience commands after installing the tools:
make -C docs html
make -C docs clean
On Windows, use docs\make.bat html. To check external links separately:
uv run --no-sync sphinx-build -b linkcheck docs docs/_build/linkcheck -W --keep-going
The HTML build treats warnings as errors, including unresolved internal
references. The link check requires network access and is a separate manual
check. Generated files belong in docs/_build/ and are ignored by Git.
Organization and style¶
Write pages in reStructuredText and add them to a toctree. The layout
separates tutorials (guided learning), how-to guides (specific tasks),
explanation (concepts), and reference (API details). Keep installation and
contributor instructions at the top level. Split section landing pages into
smaller pages as the documentation grows.
Use Sphinx roles such as :doc: for pages and :func: for API objects,
and specify a language on code blocks. Version and author metadata come from
pyproject.toml. The API reference imports waveport and extracts the
docstrings with autodoc, so write the documentation of each object in its
docstring (in src/main.cpp for objects defined by the extension), and list
new objects in the reference pages alongside API changes. Code examples are
rendered but are not executed by the documentation build.
Publish to GitHub Pages¶
The workflow in .github/workflows/docs.yml builds HTML on pull requests,
pushes to master, and manual runs. Only successful builds from the
repository’s default branch can deploy. Pull requests have read-only
permissions and never deploy.
To enable publishing for this repository:
In GitHub, open Settings → Pages → Build and deployment and set Source to GitHub Actions.
Ensure the
github-pagesenvironment allows deployment from the default branch. GitHub creates this environment on the first deployment if needed.Merge the documentation setup into
masteror run the Documentation workflow manually on the default branch.
The deployment uploads docs/_build/html using the official Pages actions
and publishes it at https://unimilab.github.io/waveport/. The workflow uses
GITHUB_TOKEN with deployment permissions scoped to the deployment job;
no personal access token or gh-pages branch is needed. Sphinx generates
.nojekyll so GitHub Pages serves Sphinx’s underscored asset directories.
If the default branch is renamed, update the workflow’s push branch filter. For a fork, also update the documentation URL and repository links.
See the Sphinx getting-started guide and GitHub’s custom Pages workflow documentation for the underlying tooling.