Migrate documentation from Sphinx to MkDocs

.github/workflows/website.yaml

@@ -39,24 +39,19 @@ jobs:
     - name: Install the project
       run: uv sync --all-extras
 
-    - name: Render documentation index from README
-      run: |
-        cp README.md docs/source/index.md
-
     # Building
     - name: Build HTML using uv
       run: |
-        cd docs
-        uv run make tutorials_clean
-        uv run make html
+        cp README.md docs/index.md
+        cd docs && uv run make html
 
     # Upload
     - name: Upload artifacts
       uses: actions/upload-pages-artifact@v4
       with:
         name: github-pages
         retention-days: 7
-        path: docs/build/html/
+        path: site/
 
   deploy:
     # Deploy to the github-pages environment

docs/.gitignore

@@ -1 +1,2 @@
 build/
+site/

docs/Makefile

@@ -1,20 +1,26 @@
-# Minimal makefile for Sphinx documentation
+# Makefile for MkDocs documentation
 #
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+MKDOCSBUILD   ?= mkdocs
+SOURCEDIR     = .
+BUILDDIR      = site
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Please use 'make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  serve      to serve the documentation locally"
+	@echo "  tutorials  to build all tutorial formats"
+	@echo "  tutorials_md     to build tutorial markdown files"
+	@echo "  tutorials_ipynb  to build tutorial notebook files"
+	@echo "  tutorials_py     to build tutorial Python files"
+	@echo "  tutorials_clean  to clean tutorial build artifacts"
 
-.PHONY: help Makefile
+.PHONY: help html serve Makefile
 
-TUTORIALSDIR = $(SOURCEDIR)/tutorials
+TUTORIALSDIR = tutorials
 
 .PHONY: tutorials tutorials_md tutorials_ipynb tutorials_py tutorials_clean echo_tutorial_source
 
@@ -23,11 +29,11 @@ $(TUTORIALSDIR)/%.md: $(TUTORIALSDIR)/%.qmd
 	quarto render $< --to gfm
 
 # Pattern rule to build a notebook file from a qmd file
-$(TUTORIALS_DIR)/%.ipynb: $(TUTORIALS_DIR)/%.qmd
+$(TUTORIALSDIR)/%.ipynb: $(TUTORIALSDIR)/%.qmd
 	quarto convert $< --output $@
 
 # Pattern rule to build a Python file from a notebook file
-$(TUTORIALS_DIR)/%.py: $(TUTORIALS_DIR)/%.ipynb
+$(TUTORIALSDIR)/%.py: $(TUTORIALSDIR)/%.ipynb
 	sed -i.bak 's/"cell_type": "raw"/"cell_type": "markdown"/g' $<
 	jupyter nbconvert --to python $<
 	rm $<.bak
@@ -62,9 +68,8 @@ tutorials_clean:
 
 .PHONY: html
 html: $(TUTORIALS_MD)
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@cd .. && $(MKDOCSBUILD) build
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-.DEFAULT: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.PHONY: serve
+serve: $(TUTORIALS_MD)
+	@cd .. && $(MKDOCSBUILD) serve

docs/source/developer_documentation.md → docs/developer_documentation.md

@@ -46,9 +46,9 @@ A variety of coding conventions are enforced by automated tools in continuous in
 
   - In a multidimensional array of timeseries, time is always the first dimension. By default, `jax.lax.scan()` and `numpyro.contrib.control_flow.scan()` build output arrays by augmenting the first dimension, and variables are often scanned over time, making default output of scan over time sensible.
 
-## Adding Documentation to Sphinx
+## Adding Documentation to MkDocs
 
-The project uses Sphinx to generate documentation. To learn more about Sphinx, visit the [Sphinx documentation](https://www.sphinx-doc.org/en/master/).
+The project uses MkDocs to generate documentation. To learn more about MkDocs, visit the [MkDocs documentation](https://www.mkdocs.org/).
 
 ### New module or classes
 We use Sphinx's `automodule` functionality to generate module API references. When you add a new module, make sure it gets added to the documentation.
@@ -70,41 +70,40 @@ This entry tells Sphinx to generate documentation for the `HospitalAdmissions` m
 
 ### New tutorials
 
-`PyRenew` tutorials are [quarto documents](https://quarto.org) located under [./docs/source/tutorials](https://github.com/CDCgov/PyRenew/tree/main/docs/source/tutorials). Tutorials are automatically rendered using GitHub actions (see the Workflow file [here](https://github.com/CDCgov/PyRenew/actions/workflows/website.yaml)).
+`PyRenew` tutorials are [quarto documents](https://quarto.org) located under [./docs/tutorials](https://github.com/CDCgov/PyRenew/tree/main/docs/tutorials). Tutorials are automatically rendered using GitHub actions (see the Workflow file [here](https://github.com/CDCgov/PyRenew/actions/workflows/website.yaml)).
 
 To make the new tutorial available in the website, developers should follow these steps:
 
-1. Create a new `quarto` file in the `./docs/source/tutorials` directory. For instance, the `example_with_datasets.qmd` file was added to the repository.
-2. Add an entry in the `./docs/source/tutorials/index.md`, for example:
+1. Create a new `quarto` file in the `./docs/tutorials` directory. For instance, the `example_with_datasets.qmd` file was added to the repository.
+2. Add an entry in the `mkdocs.yml` navigation section under the Tutorials section, for example:
 
-````markdown
-```{toctree}
-:maxdepth: 2
-getting_started
-example_with_datasets
-```
+````yaml
+nav:
+  - Tutorials:
+    - tutorials/index.md
+    - Getting Started: tutorials/getting_started.md
+    - Example with Datasets: tutorials/example_with_datasets.md
 ````
 
-3. Add an `md` entry with the same basename as the `quarto` file in the `./docs/source/tutorials` directory. For instance, the `example_with_datasets.md` file was added to the repository. This last step can be done running the bash script [./hook_scripts/pre-commit-md-placeholder.sh](https://github.com/CDCgov/PyRenew/blob/main/hook_scripts/pre-commit-md-placeholder.sh). Note the script should be executed by `pre-commit`.
+3. Add an `md` entry with the same basename as the `quarto` file in the `./docs/tutorials` directory. For instance, the `example_with_datasets.md` file was added to the repository. This last step can be done running the bash script [./hook_scripts/pre-commit-md-placeholder.sh](https://github.com/CDCgov/PyRenew/blob/main/hook_scripts/pre-commit-md-placeholder.sh). Note the script should be executed by `pre-commit`.
 
 ### Adding new pages
 
-Sphinx also allows adding arbitrary pages. For instance, all the `PyRenew` tutorials are additional documentation. The steps to add a new page are:
-
-1. Create a `md` file in the appropriate directory. For example, this file about development was added under `./docs/source/developer_documentation.md`.
-2. Make sure the new `md` file is included in an indexed file, for instance, `./docs/source/general/ctoc.md`. Here is how it looks:
-
-````markdown
-# Complete Table Of Contents
-
-```{toctree}
-:maxdepth: 2
-../index
-../pyrenew_reference/index
-../tutorials/index
-../genindex
-../developer_documentation
-```
+MkDocs also allows adding arbitrary pages. For instance, all the `PyRenew` tutorials are additional documentation. The steps to add a new page are:
+
+1. Create a `md` file in the appropriate directory. For example, this file about development was added under `./docs/developer_documentation.md`.
+2. Make sure the new `md` file is included in the navigation section of `mkdocs.yml`. Here is how it looks:
+
+````yaml
+nav:
+  - Home: index.md
+  - API Reference:
+    - reference/index.md
+    # ... other reference pages
+  - Tutorials:
+    - tutorials/index.md
+    # ... other tutorial pages
+  - Developer Documentation: developer_documentation.md
 ````
 
 The last entry is the `developer_documentation` page.

docs/index.md

@@ -0,0 +1,125 @@
+# PyRenew: A Package for Bayesian Renewal Modeling with JAX and NumPyro.
+
+⚠️ This is a work in progress ⚠️
+
+`pyrenew` is a flexible tool for simulation and statistical inference of epidemiological models, emphasizing renewal models. Built on top of the [numpyro](https://num.pyro.ai/) Python library, `pyrenew` provides core components for model building, including pre-defined models for processing various types of observational processes. To start, visit the tutorials section on the project's website [here](https://cdcgov.github.io/PyRenew/tutorials/index.html).
+
+The following diagram illustrates the composition of the `HospitalAdmissionsModel` class. Notably, all components are modular and can be replaced with custom implementations.
+
+```mermaid
+flowchart LR
+
+  %% Elements
+  rt_proc["Random Walk Rt\nProcess (latent)"];
+  latent_inf["Latent Infections"]
+  latent_ihr["Infection to Hosp.\nrate (latent)"]
+  neg_binom["Observation process\n(hospitalizations)"]
+  latent_hosp["Latent Hospitalizations"];
+  i0["Initial infections\n(latent)"];
+  gen_int["Generation\ninterval (fixed)"];
+  hosp_int["Hospitalization\ninterval (fixed)"];
+
+  %% Models
+  basic_model(("Infections\nModel"));
+  admin_model(("Hospital Admissions\nModel"));
+
+  %% Latent infections
+  rt_proc --> latent_inf;
+  i0 --> latent_inf;
+  gen_int --> latent_inf;
+  latent_inf --> basic_model
+
+  %% Hospitalizations
+  hosp_int --> latent_hosp
+
+  neg_binom --> admin_model;
+  latent_ihr --> latent_hosp;
+  basic_model --> admin_model;
+  latent_hosp --> admin_model;
+```
+
+## Installation
+
+Install via pip with
+
+```bash
+pip install git+https://github.com/CDCgov/PyRenew@main
+```
+
+## Models Implemented With PyRenew
+
+- [CDCgov/pyrenew-covid-wastewater](https://github.com/CDCgov/pyrenew-covid-wastewater): _Models and infrastructure for forecasting COVID-19 hospitalizations using wastewater data with PyRenew._
+- [CDCgov/pyrenew-flu-light](https://github.com/CDCgov/pyrenew-flu-light/): _An instantiation in PyRenew of an influenza forecasting model used in the 2023-24 respiratory season._
+
+## Resources
+
+* [The MSR Website](https://cdcgov.github.io/PyRenew/tutorials/index.html) provides general documentation and tutorials on using MSR.
+* [The Model Equations Sheet](https://github.com/CDCgov/PyRenew/blob/main/equations.md) describe the mathematics of the renewal processes and models MSR supports.
+* Additional reading on renewal processes in epidemiology
+  * [_Semi-mechanistic Bayesian modelling of COVID-19 with renewal processes_](https://academic.oup.com/jrsssa/article-pdf/186/4/601/54770289/qnad030.pdf)
+  * [_Unifying incidence and prevalence under a time-varying general branching process_](https://link.springer.com/content/pdf/10.1007/s00285-023-01958-w.pdf)
+
+## General Disclaimer
+
+This repository was created for use by CDC programs to collaborate on public health related projects in support of the [CDC mission](https://www.cdc.gov/about/cdc/index.html#cdc_about_cio_mission-our-mission).  GitHub is not hosted by the CDC, but is a third party website used by CDC and its partners to share information and collaborate on software. CDC use of GitHub does not imply an endorsement of any one particular service, product, or enterprise.
+
+## Public Domain Standard Notice
+
+This repository constitutes a work of the United States Government and is not
+subject to domestic copyright protection under 17 USC § 105. This repository is in
+the public domain within the United States, and copyright and related rights in
+the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
+All contributions to this repository will be released under the CC0 dedication. By
+submitting a pull request you are agreeing to comply with this waiver of
+copyright interest.
+
+## License Standard Notice
+
+This repository is licensed under ASL v2 or later.
+
+This source code in this repository is free: you can redistribute it and/or modify it under
+the terms of the Apache Software License version 2, or (at your option) any
+later version.
+
+This source code in this repository is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the Apache Software License for more details.
+
+You should have received a copy of the Apache Software License along with this
+program. If not, see [http://www.apache.org/licenses/LICENSE-2.0.html](http://www.apache.org/licenses/LICENSE-2.0.html).
+
+The source code forked from other open source projects will inherit its license.
+
+## Privacy Standard Notice
+
+This repository contains only non-sensitive, publicly available data and
+information. All material and community participation is covered by the
+[Disclaimer](https://github.com/CDCgov/template/blob/master/DISCLAIMER.md)
+and [Code of Conduct](https://github.com/CDCgov/template/blob/master/code-of-conduct.md).
+For more information about CDC's privacy policy, please visit [http://www.cdc.gov/other/privacy.html](https://www.cdc.gov/other/privacy.html).
+
+## Contributing Standard Notice
+
+Anyone is encouraged to contribute to the repository by [forking](https://help.github.com/articles/fork-a-repo)
+and submitting a pull request. (If you are new to GitHub, you might start with a
+[basic tutorial](https://help.github.com/articles/set-up-git).) By contributing
+to this project, you grant a world-wide, royalty-free, perpetual, irrevocable,
+non-exclusive, transferable license to all users under the terms of the
+[Apache Software License v2](http://www.apache.org/licenses/LICENSE-2.0.html) or
+later.
+
+All comments, messages, pull requests, and other submissions received through
+CDC including this GitHub page may be subject to applicable federal law, including but not limited to the Federal Records Act, and may be archived. Learn more at [http://www.cdc.gov/other/privacy.html](http://www.cdc.gov/other/privacy.html).
+
+## Records Management Standard Notice
+
+This repository is not a source of government records but is a copy to increase
+collaboration and collaborative potential. All government records will be
+published through the [CDC web site](http://www.cdc.gov).
+
+## Additional Standard Notices
+
+Please refer to [CDC's Template Repository](https://github.com/CDCgov/template)
+for more information about [contributing to this repository](https://github.com/CDCgov/template/blob/master/CONTRIBUTING.md),
+[public domain notices and disclaimers](https://github.com/CDCgov/template/blob/master/DISCLAIMER.md),
+and [code of conduct](https://github.com/CDCgov/template/blob/master/code-of-conduct.md).

docs/javascripts/mathjax.js

@@ -0,0 +1,16 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise()
+})

docs/reference/additional.md

@@ -0,0 +1,25 @@
+# Additional modules
+
+## Metaclass Module
+
+::: pyrenew.metaclass
+
+## Convolution Utility Module
+
+::: pyrenew.convolve
+
+## Mathematics Utilities Module
+
+::: pyrenew.math
+
+## Transformations Module
+
+::: pyrenew.transformation
+
+## Regression Module
+
+::: pyrenew.regression
+
+## Distributions Utility Module
+
+::: pyrenew.distutil

docs/reference/datasets.md

@@ -0,0 +1,13 @@
+# Datasets
+
+## Generation interval
+
+::: pyrenew.datasets.generation_interval
+
+## Infection to admission interval
+
+::: pyrenew.datasets.infection_admission_interval
+
+## Simulated Wastewater Data
+
+::: pyrenew.datasets.wastewater

docs/reference/deterministic.md

@@ -0,0 +1,3 @@
+# Deterministic
+
+::: pyrenew.deterministic