beykyle · Copilot · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026 · Copilot
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,50 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r docs/requirements.txt
+          python -m pip install -e .
+      - name: Build HTML docs
+        run: sphinx-build -b html docs docs/_build/html
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
@@ -11,7 +11,14 @@ An example of this code in use is in the development of the [East Lansing Model]
 Check out the [`examples/` directory](https://github.com/beykyle/rxmc/blob/main/examples/).
 
 ## documentation
-- TBD
+- Build locally with:
+  ```bash
+  pip install -e .
+  pip install -r docs/requirements.txt
+  sphinx-build -b html docs docs/_build/html
+  ```
+- API docs are generated automatically from docstrings via Sphinx autodoc.
+- Documentation is published to GitHub Pages by `.github/workflows/docs.yml`.
 
 ## installation
 ### pypi

diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,47 @@
+API reference
+=============
+
+.. automodule:: rxmc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: rxmc.params
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: rxmc.observation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: rxmc.constraint
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: rxmc.evidence
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: rxmc.likelihood_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: rxmc.physical_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: rxmc.param_sampling
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: rxmc.walker
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,26 @@
+"""Sphinx configuration for rxmc documentation."""
+
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+project = "rxmc"
+copyright = "2026, rxmc contributors"
+author = "rxmc contributors"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+]
+
+autosummary_generate = True
+napoleon_numpy_docstring = True
+napoleon_google_docstring = False
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build"]
+
+html_theme = "alabaster"
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,10 @@
+rxmc documentation
+==================
+
+`rxmc` provides tools for Bayesian calibration of reaction models.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   api
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1 @@
+sphinx>=8
diff --git a/src/rxmc/__init__.py b/src/rxmc/__init__.py
@@ -1,3 +1,5 @@
+"""Public package exports for rxmc."""
+
 from . import physical_model
 from . import likelihood_model
 from . import evidence

diff --git a/src/rxmc/adaptive_metropolis.py b/src/rxmc/adaptive_metropolis.py
@@ -1,3 +1,5 @@
+"""Adaptive Metropolis sampling algorithms."""
+
 import numpy as np
 from typing import Callable, Tuple
 
@@ -14,8 +16,8 @@ def adaptive_metropolis(
 ) -> Tuple[np.ndarray, np.ndarray, int]:
     """
     Adaptive Metropolis algorithm with a sliding window covariance adaptation.
-        Parameters:
-        ---------
+        Parameters
+        ----------
         x0 : np.ndarray
             Initial point in the parameter space.
         n_steps : int

diff --git a/src/rxmc/constraint.py b/src/rxmc/constraint.py
@@ -1,3 +1,5 @@
+"""Constraint composition of observations, models, and likelihoods."""
+
 import numpy as np
 
 from .likelihood_model import LikelihoodModel
@@ -28,7 +30,7 @@ def __init__(
         """
         Initialize the Constraint with some Observations, a PhysicalModel, and
 
-        Parameters:
+        Parameters
         ----------
         observations: list[Observation]
             The observed data that the model will attempt to reproduce.
@@ -47,7 +49,7 @@ def model(self, model_params):
         """
         Compute the model output for each observation, given model_params.
 
-        Parameters:
+        Parameters
         ----------
         model_params : tuple
             The parameters of the physical model
@@ -59,16 +61,16 @@ def log_likelihood(self, model_params, likelihood_params=()):
         Calculate the log probability density function that the
         model predictions, given the parameters, reproduce the observed data.
 
-        Parameters:
+        Parameters
         ----------
         model_params : tuple
             The parameters of the physical model
         likelihood_params : tuple, optional
             Additional parameters for the likelihood model, if any.
 
 
-        Returns:
-        -------
+        Returns
+        ----------
         float
             The log probability density of the observation given the
             parameters.
@@ -86,16 +88,16 @@ def marginal_log_likelihood(self, ym: list, *likelihood_params):
         likelihood_params provided, reproduces the observations in the
         constraints.
 
-        Parameters:
+        Parameters
         ----------
         ym : list
             The model predictions for the observed data.
         likelihood_params : tuple, optional
             Additional parameters for the likelihood model, if any.
 
 
-        Returns:
-        -------
+        Returns
+        ----------
         float
             The log probability density of the observation given the
             parameters.
@@ -110,15 +112,15 @@ def chi2(self, model_params, likelihood_params=()):
         Calculate the chi-squared statistic (or Mahalanobis distance) between
         the model prediction, given the parameters, and the observed data.
 
-        Parameters:
+        Parameters
         ----------
         model_params : tuple
             The parameters of the physical model
         likelihood_params : tuple, optional
             Additional parameters for the likelihood model, if any.
 
-        Returns:
-        -------
+        Returns
+        ----------
         float
             The chi-squared statistic.
         """
@@ -134,13 +136,13 @@ def predict(self, *model_params):
         Generate predictions for each observation using the physical model
         with the provided parameters.
 
-        Parameters:
+        Parameters
         ----------
         *model_params : tuple
             The parameters of the physical model.
 
-        Returns:
-        -------
+        Returns
+        ----------
         list[np.ndarray]
             The predicted values for each observation.
         """
@@ -153,7 +155,7 @@ def num_pts_within_interval(
         Count the number of points within the specified interval for each
         observation.
 
-        Parameters:
+        Parameters
         ----------
         ylow : list[np.ndarray]
             Lower bounds of the intervals for each observation.
@@ -162,8 +164,8 @@ def num_pts_within_interval(
         xlim : tuple, optional
             Limits for the x-axis, if applicable.
 
-        Returns:
-        -------
+        Returns
+        ----------
         int
             The total number of points within the specified intervals across
             all observations.
@@ -181,7 +183,7 @@ def empirical_coverage(
         specified intervals for each observation, as a fraction of the total
         number of data points.
 
-        Parameters:
+        Parameters
         ----------
         ylow : list[np.ndarray]
             Lower bounds of the intervals for each observation.
@@ -190,8 +192,8 @@ def empirical_coverage(
         xlim : tuple, optional
             Limits for the x-axis, if applicable.
 
-        Returns:
-        -------
+        Returns
+        ----------
         float
             The empirical coverage across all observations.
         """

diff --git a/src/rxmc/correlated_discrepancy_likelihood_model.py b/src/rxmc/correlated_discrepancy_likelihood_model.py
@@ -1,3 +1,5 @@
+"""Likelihood models with correlated discrepancy terms."""
+
 import numpy as np
 from sklearn.gaussian_process.kernels import Kernel
 
@@ -56,6 +58,8 @@ def _kernel_matrix(
         return k(X)  # (N,N)
 
     def covariance(self, observation: Observation, ym: np.ndarray, *kernel_theta):
+        """Return covariance including observational and discrepancy components."""
+
         if len(kernel_theta) != self.n_params:
             raise ValueError(
                 f"Expected {self.n_params} kernel hyperparameters, got {len(kernel_theta)}"
@@ -70,4 +74,3 @@ def covariance(self, observation: Observation, ym: np.ndarray, *kernel_theta):
             cov = cov + self.jitter * np.eye(observation.n_data_pts)
 
         return cov
-
diff --git a/src/rxmc/elastic_diffxs_model.py b/src/rxmc/elastic_diffxs_model.py
@@ -1,3 +1,5 @@
+"""Physical models for elastic differential cross sections."""
+
 from typing import Callable
 
 import jitr
@@ -26,7 +28,7 @@ def __init__(
         """
         Initialize the ElasticDifferentialXSModel with the interactions and
         a function to calculate the subparameters.
-        Parameters:
+        Parameters
         ----------
         quantity : str
             The type of quantity to be calculated (e.g., "dXS/dA",
@@ -75,15 +77,15 @@ def evaluate(
         """
         Evaluate the model at the given parameters.
 
-        Parameters:
+        Parameters
         ----------
         observation : ElasticDifferentialXSObservation
             The observation containing the reaction data and workspace.
         params : tuple
             The parameters of the physical model.
 
-        Returns:
-        -------
+        Returns
+        ----------
         np.ndarray
             An array, containing the evaluated differential data on the
             angular grid corresponding to the
@@ -109,15 +111,15 @@ def visualizable_model_prediction(
         """
         Visualize the model at the given parameters.
 
-        Parameters:
+        Parameters
         ----------
         observation : ElasticDifferentialXSObservation
             The observation containing the reaction data and workspace.
         params : tuple
             The parameters of the physical model.
 
-        Returns:
-        -------
+        Returns
+        ----------
         np.ndarray
             An array, containing the evaluated differential data on the
             angular grid corresponding to the
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		sphinx>=8
Copy link Copilot AI Mar 3, 2026 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. The docs toolchain declares `sphinx>=8` in `docs/requirements.txt`, and this file is installed in CI by the `docs` GitHub Actions workflow, so arbitrary future `sphinx` releases (or a compromised package with that name) will be executed in a privileged Actions environment. This creates a supply-chain risk where a malicious `sphinx` release could run code during the docs build and exfiltrate `GITHUB_TOKEN` or tamper with published documentation. To mitigate this, pin `sphinx` to a specific, trusted version (and update it via an automated dependency updater) so CI always uses a known-good release. Copilot uses AI. Check for mistakes.