Maintaining the documentation

The Markdown files in docs/ are the source for Read the Docs. Keep the README limited to the original abstract, installation/test essentials, the conceptual diagram and links to the complete guide. Edit detailed instructions here; do not maintain separate copies on the website.

Build and review locally

Use a separate documentation environment:

mamba create -n metapathways-docs -c conda-forge python=3.11 pip
conda activate metapathways-docs
python -m pip install -r docs/requirements.txt
python -m sphinx -W --keep-going -b html docs docs/_build/html
python -m http.server 8000 --directory docs/_build/html

Open http://localhost:8000. The documentation build does not install MP, reference databases, or Pathway Tools. It uses the committed CLI reference; after changing CLI arguments, regenerate that page from an MP development environment with python scripts/generate_cli_docs.py.

Mermaid sources live in docs/diagrams/; GitHub and Read the Docs display the committed SVG previews at a shared scale. Keep the conceptual diagram in the README consistent with overview.md. The GitHub documentation job builds with warnings treated as errors.

Connect Read the Docs

In the existing metapathways project, connect hallamlab/MetaPathways. The configuration file is .readthedocs.yaml, the Sphinx configuration is docs/conf.py, and dependencies are in docs/requirements.txt.

Activate the branch you want to preview under Versions and trigger a build. Keep the public default on the intended main/development branch; switch it to the updated branch after the documentation is merged. Enable pull-request previews if desired. Branch previews allow review before changing the site’s default version.

The project address stays https://hallamlab-metapathways.readthedocs.io/. Repository changes supply the build configuration; linking the project, version activation and default-version settings are managed in Read the Docs. Confirm a successful build there before announcing updated hosted pages.

The previous quick_start.html, install.html and usage.html addresses redirect to the corresponding new pages.

Shared diagram scale

ASPIRE and MetaPathways use a shared 2,240-unit-wide white canvas for documentation previews. MP’s main workflow in the README and documentation home page uses its cropped SVG at full available width for readability. Smaller diagrams are centered without stretching; Mermaid diagrams use a common 1.5× scale to bring their 16-pixel labels close to the publication figures’ typography. Preview width is responsive, but relative scale stays consistent across pages. Click a diagram to open its SVG for closer inspection. Original publication SVG/PDF downloads stay tightly cropped.

Edit Mermaid sources under docs/diagrams/, or the original publication SVGs under docs/assets/. To rebuild the committed previews from the repository root, in the documentation environment:

python -m pip install -r docs/diagram-requirements.txt
python -m playwright install chromium
python scripts/render_workflow_diagrams.py

Chromium requires its usual Linux system libraries. Rendering downloads the pinned Mermaid bundle; ordinary Sphinx builds need neither Chromium nor network access for diagrams. docs/diagrams/figures.json records the source mapping and shared canvas size. If a future diagram needs a wider canvas, update both projects together. Do not hand-edit generated files in docs/assets/diagrams/.