Build comprehensive Read the Docs documentation

[linsalrob]

What changed

• complete the Read the Docs/Sphinx configuration with pinned Python 3.13 build dependencies, MyST Markdown, and the Read the Docs theme
• add a navigable 14-page documentation set covering the project overview, design rationale, installation, profile selection, quick start, configuration, pipeline stages, outputs, troubleshooting, utilities, scientific methods, cluster porting, and contribution guidance
• reconcile existing repository guidance with the JOSS draft's description of the project's motivation, failure-isolation design, HPC portability choices, and current scientific workflow
• document safe, reviewable use of agentic AI when adapting a cluster profile

Why

The branch previously contained a Read the Docs configuration pointing to a missing docs/conf.py and only one documentation page. New users and cluster contributors did not have a coherent route from installation through a complete run, nor an explanation of the design trade-offs and profile-porting requirements.

User impact

Users now have task-oriented onboarding and reference documentation for paired and single/long-read workflows. Contributors have explicit validation, security, scheduler-policy, and pull-request guidance. The existing README.md and joss:paper/paper.md were used as read-only sources and were not modified.

Validation

• sphinx-build -W --keep-going -b html docs /tmp/atavide-rtd-html succeeded with Sphinx 7.4.7/MyST 3.0.1 (local Python-compatible validation of the Sphinx 8/MyST 4 deployment configuration)
• .readthedocs.yaml parsed and its Sphinx/requirements paths were verified
• python -m unittest discover -s tests -v passed all 3 tests
• git diff --check passed
• staged scope confirmed to exclude README.md, paper/paper.md, and unrelated data

[Copilot]

Pull request overview

This PR builds out a comprehensive Read the Docs / Sphinx documentation set for atavide_lite, adding a full navigation structure and a multi-page user + contributor guide, along with the RTD build configuration and pinned doc build dependencies.

Changes:

• Add Read the Docs configuration plus Sphinx config (docs/conf.py) and pinned documentation requirements.
• Introduce a multi-page documentation set covering onboarding, configuration, pipeline stages, outputs, troubleshooting, utilities, methods, cluster porting, and contributing.
• Align docs narrative with the project’s stated design rationale (stage isolation, HPC portability, and explicit operational contracts).

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
.readthedocs.yaml	Configures RTD build OS/Python and points RTD at the Sphinx config + requirements.
docs/conf.py	Defines Sphinx project configuration (theme, MyST, nitpicky mode, static path).
docs/requirements.txt	Pins Sphinx/MyST/theme dependencies for doc builds.
docs/index.md	Adds landing page and toctree navigation structure for the doc set.
docs/overview.md	Provides high-level motivation/scope for the pipeline and its usage model.
docs/design.md	Documents design rationale and trade-offs (explicit stages, restartability, portability).
docs/installation.md	Step-by-step installation and environment/database prerequisites.
docs/profiles.md	Guides users in selecting the appropriate cluster/profile by read type and scheduler model.
docs/quickstart.md	Walkthrough for a first small run including job submission/dependencies.
docs/configuration.md	Documents the analysis directory contract and DEFINITIONS.sh variables.
docs/pipeline.md	Explains pipeline stages, dependencies, and validation expectations.
docs/outputs.md	Describes stable output concepts, logs, and reproducibility records.
docs/troubleshooting.md	Adds a practical diagnostic checklist for common HPC/pipeline failures.
docs/utilities.md	Indexes repo utilities/components and explains when/how to use them.
docs/methods.md	Updates/expands scientific methods and reproducible reporting guidance.
docs/contributing.md	Adds contribution workflow and guidance (including safe use of agentic AI).
docs/cluster-support.md	Adds a structured cluster-porting guide/checklist and validation expectations.
docs/_static/.gitkeep	Ensures _static/ exists for Sphinx static assets.

Suppressed comments (1)

.readthedocs.yaml:21

• The file ends with whitespace-only lines. Trailing whitespace can fail whitespace checks and makes diffs noisier; remove the blank/whitespace-only lines at the end of the config.

  install:
    - requirements: docs/requirements.txt
        

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.