Contributing to Documentation#
Documentation is crucial for SpectroChemPy. You don’t need to be an expert to help - if something isn’t clear, improving it helps everyone!
Documentation Structure#
SpectroChemPy documentation consists of:
Docstrings in the code (API reference)
Guides and tutorials in the
docs/folderExamples in Jupyter notebooks
We use:
reStructuredText (reST) markup
Sphinx documentation builder
NumPy docstring standard
Jupyter notebooks for tutorials
Documentation Sources#
API Documentation#
Lives in docstrings within Python code
Follows NumPy docstring standard
Examples are tested during builds
Located in
docs/reference
Guides & Tutorials#
Written in reST or Jupytext Python files with
# %%cellsLocated in
docs/sources/userguide/Provide high-level overviews and examples
All code examples are tested
Building Documentation#
Quick Start#
Set up development environment (guide)
From the repository root, build HTML:
python docs/make.py html
View at
build/html/index.html
For documentation-only edits where executing examples is not needed, use:
python docs/make.py --no-exec html
On the published site, the root contains the latest stable documentation.
Unreleased documentation from master is published under latest/.
Stable releases also remain available under version directories such as
VERSION/. The stable snapshot is built from its published Git tag and is
never replaced with documentation built from master. Documentation-focused
branches publish identifiable previews under their sanitized branch name and do
not redirect to stable documentation.
Build Options#
Full rebuild:
python docs/make.py clean python docs/make.py html
Build a single file:
python docs/make.py --single-doc <path-to-file-relative-to-docs>.rst python docs/make.py --single-doc <path-to-file-relative-to-docs>.ipynb
Build a single directory:
python docs/make.py --directory <path-to-directory-relative-to-docs>
Build a single API entry:
python docs/make.py --single-doc spectrochempy.<class-or-method-name> # where ``<class-or-method-name>`` is the name of an importable method in the API.
Preview a Gallery Example or Tutorial#
From the repository root, use the documentation environment to render the
page you are editing. For a gallery example, pass the script path relative to
the repository root. This also works with scripts under a plugin’s
examples/ directory.
python -m docs.make html --gallery-example src/spectrochempy/examples/core/a_nddataset/plot_a_create_dataset.py
For a tutorial, pass its Jupytext source path relative to docs/sources/.
The preview reads the Python file directly.
python -m docs.make html --single-doc userguide/plotting/plot_types.py
Each command prints the absolute path to the generated HTML page under
build/preview/. Open that page in a browser and keep the surrounding
files so its styles and figures load. The preview uses the data and plugins
available in the local documentation environment. Tutorials also need a
working Jupyter python3 kernel. For prose or layout edits, add
--no-exec to render the page without running its code or regenerating its
figures.
If your browser or editor preview needs an HTTP URL, reuse a local server
already serving this worktree’s build/preview/ directory. To start one,
run this command from the repository root.
python -m http.server 8765 --bind 127.0.0.1 --directory build/preview
If port 8765 is busy, choose a free port and use it in the preview URL.
Append the printed HTML path relative to build/preview/ to
http://127.0.0.1:8765/. After editing, rerun the preview command and
refresh the page in your browser. The URL works while the server is running.
Documentation CI Artifacts#
The documentation artifact workflow runs on pushes to master and release tags. It can also be triggered manually. The tutorial and gallery jobs check out the workflow commit. The tutorial job saves executed notebooks. The gallery job saves generated reStructuredText, figures, thumbnails, downloads, and API backreferences. The final job checks the commit and file hashes of both artifacts before rendering one Sphinx site with the usual configuration and document paths. Download the HTML artifact from the workflow run to inspect the result.
Before enabling artifact mode in production, validate it on a separate Read
the Docs test project with the same build time limit. Configure
SCPY_RTD_DOCS_ARTIFACTS=1 and set SCPY_RTD_GITHUB_TOKEN as a private
environment variable with read access to Actions in the SpectroChemPy
repository. Verify that the hosted build uses artifacts from its exact
checkout SHA and installed SpectroChemPy version, keeps the expected URLs and navigation, and completes within
the time limit, including dependency installation, the CI wait, and rendering.
If the concurrent workflow and RTD build exceed that limit, arrange for CI to
finish before triggering RTD. External pull request previews execute their
sources inside RTD.
RTD waits up to 15 minutes for a successful workflow with both artifacts for
its checkout. If artifacts expire, start a new workflow run with
workflow_dispatch in the upstream SpectroChemPy repository. Verify that
the run uses the exact checkout SHA and retry RTD once CI succeeds. If the
ref has moved and you need the old SHA, dispatch CI on a temporary branch at that SHA and build
the corresponding RTD version of the temporary branch. To retry the original
RTD version instead, generate artifacts for its current SHA. To restore
execution inside RTD, unset SCPY_RTD_DOCS_ARTIFACTS.
Writing Tips#
Use active voice
Be concise
Include practical examples
Test all code examples
Link related sections
Follow docstring guide
See the Sphinx reStructuredText primer for detailed syntax guide.