Contributing to the documentation¶
The site follows the MISTIC documentation pattern: Sphinx, Furo, guided tutorials, reproducible figures, downloadable examples, and an API reference generated from public docstrings. Protspect’s existing Markdown guides remain the authoritative technical notes rather than being copied into separate pages.
Build and verify¶
From a development checkout:
python -m pip install -e '.[docs]'
python -m docs.generate_tutorial_figures
python -m sphinx -W --keep-going -b html docs docs/_build/html
python -m ci.check_docs_links docs/_build/html
python -m sphinx -W --keep-going -b doctest docs docs/_build/doctest
python -m ci.check_tutorials --output docs/_build/notebooks
python -m http.server 8000 --directory docs/_build/html
Open http://localhost:8000 in your browser. Generated HTML and executed
notebooks are ignored. Figure source lives in docs/generate_tutorial_figures.py.
The downloadable source notebooks in protspect/examples contain no stale
outputs. CI executes them in a writable temporary directory with no network
requirements. Their synthetic sequences teach API usage, not biological accuracy.
PROTSPECT_DOCS_REF controls GitHub source links for a branch preview;
PROTSPECT_DOCS_BASEURL optionally sets the canonical deployed URL. The default
build is a development snapshot and does not claim a new PyPI release.
Review and publishing¶
The documentation workflow builds PR previews and uploads HTML artifacts. It
also supports a manual Pages publication request; publication is off by default.
Publishing needs repository GitHub Pages configured to use GitHub Actions and
the github-pages environment. No repository Pages settings are changed by
building these sources.
Keep numerical examples runnable and link every new page in a toctree. Run the
strict HTML/doctest builds before opening a PR. Preserve the distinction between
full-coefficient exports and historical Fourier closure/dyadic exports. Never
bundle private peptide datasets or downloaded AAindex files. General contribution
instructions are in the repository’s CONTRIBUTING.md.