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:

  1. In GitHub, open Settings → Pages → Build and deployment and set Source to GitHub Actions.

  2. Ensure the github-pages environment allows deployment from the default branch. GitHub creates this environment on the first deployment if needed.

  3. Merge the documentation setup into master or 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.