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:

  1. Docstrings in the code (API reference)

  2. Guides and tutorials in the docs/ folder

  3. Examples 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 # %% cells

  • Located in docs/sources/userguide/

  • Provide high-level overviews and examples

  • All code examples are tested

Building Documentation#

Quick Start#

  1. Set up development environment (guide)

  2. From the repository root, build HTML:

    python docs/make.py html
    
  3. 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.
    

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#

  1. Use active voice

  2. Be concise

  3. Include practical examples

  4. Test all code examples

  5. Link related sections

  6. Follow docstring guide

See the Sphinx reStructuredText primer for detailed syntax guide.