docs: migrate to Sphinx + ReadTheDocs

[shreyamukherji]

Migrate docs from MkDocs to Sphinx (MyST). Adds .readthedocs.yaml and CI.

Summary by CodeRabbit

Release Notes

• New Features

  • Added starter model templates (SIR, SEIR, SIRS, SIS) for project initialization
  • Introduced --json flag for machine-readable output across CLI commands
  • Added --template option to select model templates during project setup
  • Enhanced configuration path resolution for file references

• Documentation

  • Migrated documentation from MkDocs to Sphinx with ReadTheDocs integration
  • Added comprehensive CLI reference, configuration guide, and mathematical model documentation
  • Expanded getting-started guide and results analysis walkthrough

• Changes

  • Strengthened input validation for seed data and compartments
  • Updated package to Beta status
  • Improved CLI command output structure for programmatic use

• Refactor

  • Removed deprecated loader utilities module

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bd50a7ed-08c4-4220-b374-ef43b4f9c93f

📥 Commits

Reviewing files that changed from the base of the PR and between 75537d8 and c8a625a.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (32)

• .github/workflows/docs-sphinx.yml
• .github/workflows/publish.yml
• .readthedocs.yaml
• CHANGELOG.md
• README.md
• docs/_static/.gitkeep
• docs/cli-reference.md
• docs/conf.py
• docs/configuration.md
• docs/getting-started.md
• docs/index.md
• docs/mathematical-model.md
• docs/rate-multiplication.md
• docs/reference/core.md
• docs/reference/models.md
• docs/reference/utils.md
• docs/requirements-docs.txt
• docs/results.md
• mkdocs.yml
• pyproject.toml
• src/patchsim/cli.py
• src/patchsim/core/simulation.py
• src/patchsim/models/ka_fmd_sirsv_discrete.py
• src/patchsim/templates/models/seir.yaml
• src/patchsim/templates/models/sir.yaml
• src/patchsim/templates/models/sirs.yaml
• src/patchsim/templates/models/sis.yaml
• src/patchsim/utils/loader.py
• test.py
• tests/test_config.py
• tests/test_simulation_setup.py
• tests/test_smoke.py

---

📝 Walkthrough

Walkthrough

This PR transforms PatchSim into a production-ready beta release by migrating documentation from MkDocs to Sphinx, introducing built-in compartmental model templates, enhancing the CLI with JSON output and template selection, significantly expanding user-facing documentation, and updating dependencies and publishing workflows.

Changes

Beta Release Preparation

Layer / File(s)	Summary
Sphinx documentation infrastructure .github/workflows/docs-sphinx.yml, .readthedocs.yaml, docs/conf.py, docs/requirements-docs.txt, mkdocs.yml (removed), docs/reference/* (removed)	Replaces MkDocs with Sphinx/MyST, configures MyST extensions and theme, sets up Read the Docs integration with frozen uv sync, and removes mkdocstrings-based reference pages.
Built-in model templates and core enhancements src/patchsim/templates/models/*.yaml, src/patchsim/core/simulation.py, tests/test_config.py, tests/test_simulation_setup.py	Introduces SIR, SEIR, SIRS, SIS templates; adds MODEL_TEMPLATE_CONFIGS and schema/catalog helpers; strengthens load_config to resolve relative paths and validate required fields; expands seed/compartment/transition validation with stricter error checking and identifier extraction; run_simulation now returns a summary dict.
CLI enhancements for JSON output and templates src/patchsim/cli.py	Refactors _cmd_run, _cmd_validate, _cmd_list_models to return structured data; adds _emit_json helper; adds --json and --schema flags for JSON/schema output; _cmd_init now accepts --template option with dynamic choices; logging suppresses rich output in JSON mode.
User-facing documentation expansion docs/getting-started.md, docs/configuration.md, docs/mathematical-model.md, docs/results.md, docs/rate-multiplication.md, docs/cli-reference.md, docs/index.md, README.md	Expands getting-started with hands-on walkthrough including JSON output mode; comprehensive configuration reference with examples and validation workflow; mathematical-model with SIR/SEIR/SIRS/SIS/custom sections, rate-multiplication principle, and assumptions; results guide with CSV/PNG/log interpretation and Python analysis examples; new CLI reference documenting all commands, options, and common errors; updated index with toctree and logical reading path.
Project metadata and publishing pyproject.toml, .github/workflows/publish.yml, CHANGELOG.md, test.py (removed), README.md (CLI section)	Pins core and optional dependencies with version constraints, restructures optional groups into test/docs/lint, updates to Beta classifier; enhances publish workflow with twine check pre-validation and tag filtering for version-like releases; adds initial CHANGELOG for 0.1.0b1; removes deprecated test.py.
Test coverage for new features tests/test_config.py, tests/test_simulation_setup.py, tests/test_smoke.py	Validates config path resolution, transition identifier validation, compartment mismatch detection; verifies --json mode returns correct structure for list-models and run; tests --schema returns JSON schema with expected title; confirms --template seir scaffolds correct config.
Deprecations and cleanup src/patchsim/utils/loader.py, src/patchsim/models/ka_fmd_sirsv_discrete.py	Converts loader module to deprecation placeholder pointing to patchsim.core.simulation; removes discrete Weibull-waning SIRSV model implementations (330 lines).

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• dsih-artpark/patchsim#3: Directly preceding PR that refactored the CLI structure and added initial main(), _cmd_init(), and logging helpers that this PR extends with JSON/schema output modes and template selection integration.

Poem

🐰 Sphinx lights the way with docs so grand,
Templates bloom across the land,
JSON flows and schemas gleam,
Beta launch fulfills the dream! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/sphinx-rtd-pr

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[AdishAssain]

Thanks! Two things before merge:

1. CI is red — ruff check fails on docs/conf.py (L33–34: E402, I001). Run uv run ruff check --fix docs/conf.py and move the sphinx.highlighting / pygments imports to the top (or add # noqa: E402 if they need to run after setup).
2. Delete docs/requirements-docs.txt — it's outdated and .readthedocs.yaml uses the [docs] extra from pyproject.toml instead. Also remove mkdocs.yml.

Once CI is green, good to merge.