Add docs

.github/copilot_instructions.md

@@ -18,7 +18,7 @@ python -m black --check src test
 python -m ruff check src test
 python -m nbqa isort --check examples/*.ipynb
 python -m black --check --ipynb examples/*.ipynb
-python -m nbqa ruff examples/*.ipynb
+python -m ruff check examples/*.ipynb
 python -m pytest
 ```
 

.github/workflows/ci.yml

@@ -8,6 +8,10 @@ on:
     branches:
       - main
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   format:
     runs-on: ubuntu-latest
@@ -18,6 +22,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+          cache: 'pip'
 
       - name: Install validation dependencies
         run: |
@@ -34,7 +39,7 @@ jobs:
         run: |
           python -m nbqa isort --check examples/*.ipynb
           python -m black --check --ipynb examples/*.ipynb
-          python -m nbqa ruff examples/*.ipynb
+          python -m ruff check examples/*.ipynb
 
   tests:
     runs-on: ubuntu-latest
@@ -49,6 +54,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: 'pip'
 
       - name: Install validation dependencies
         run: |
@@ -60,13 +66,15 @@ jobs:
 
   notebooks:
     runs-on: ubuntu-latest
+    timeout-minutes: 45
 
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+          cache: 'pip'
 
       - name: Install validation dependencies
         run: |
@@ -85,6 +93,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+          cache: 'pip'
 
       - name: Build distributions
         run: |

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: 'pip'
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -e '.[docs]'
+
+      - name: Build HTML docs
+        run: |
+          ln -sf ../examples docs/examples
+          sphinx-build docs docs/_build/html -W --keep-going
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy-docs:
+    needs: build-docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,6 +1,9 @@
 # 
 examples/*.pdf
 
+# docs
+docs/_build/
+
 #slurm
 *.out
 

README.md

@@ -165,6 +165,19 @@ entry points are:
 - `examples/normalization_inference.ipynb` for normalization-focused modeling,
 - `examples/sampling_algos.ipynb` for sampling comparisons.
 
+## Documentation
+
+The full API reference and rendered example notebooks are hosted at
+**https://beykyle.github.io/rxmc/**.
+
+To build the documentation locally:
+
+```bash
+pip install -ve '.[docs]'
+cd docs && make html
+# then open docs/_build/html/index.html
+```
+
 ## Testing
 
 Run the full validation matrix with:
@@ -175,7 +188,7 @@ python -m black --check src test
 python -m ruff check src test
 python -m nbqa isort --check examples/*.ipynb
 python -m black --check --ipynb examples/*.ipynb
-python -m nbqa ruff examples/*.ipynb
+python -m ruff check examples/*.ipynb
 python -m pytest
 ```
 
@@ -187,7 +200,6 @@ python -m black src test
 python -m ruff check --fix src test
 python -m nbqa isort examples/*.ipynb
 python -m black --ipynb examples/*.ipynb
-python -m nbqa ruff --fix --unsafe-fixes examples/*.ipynb
 ```
 
 Run only the unit tests with:

docs/Makefile

@@ -0,0 +1,17 @@
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help html clean
+
+help:
+	@$(SPHINXBUILD) -M help $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS) $(O)
+
+html:
+	test -L examples || ln -sf ../examples examples
+	$(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O)
+	@echo
+	@echo "Build finished. Open $(BUILDDIR)/html/index.html to view."
+
+clean:
+	rm -rf $(BUILDDIR) generated examples

docs/api.rst

@@ -0,0 +1,107 @@
+API Reference
+=============
+
+Configuration
+-------------
+
+High-level configuration objects for assembling a calibration problem and
+handing it to an external sampler (emcee, dynesty, etc.).
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   rxmc.config.CalibrationConfig
+   rxmc.config.ParameterConfig
+
+Priors
+------
+
+Prior distribution classes that satisfy the generic prior protocol required by
+:class:`~rxmc.config.ParameterConfig`.  Any user-defined class with ``logpdf``,
+``rvs``, and (optionally) ``prior_transform`` methods can be used directly.
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   rxmc.priors.IndependentPrior
+   rxmc.priors.TruncatedNormalPrior
+
+Core building blocks
+--------------------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   rxmc.constraint.Constraint
+   rxmc.evidence.Evidence
+   rxmc.observation.Observation
+   rxmc.observation.FixedCovarianceObservation
+   rxmc.params.Parameter
+   rxmc.physical_model.PhysicalModel
+   rxmc.physical_model.Polynomial
+
+Likelihood models
+-----------------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   rxmc.likelihood_model.LikelihoodModel
+   rxmc.likelihood_model.FixedCovarianceLikelihood
+   rxmc.likelihood_model.Chi2LikelihoodModel
+   rxmc.likelihood_model.ParametricLikelihoodModel
+   rxmc.likelihood_model.UnknownNoiseErrorModel
+   rxmc.likelihood_model.UnknownNoiseFractionErrorModel
+   rxmc.likelihood_model.UnknownNormalizationModel
+   rxmc.likelihood_model.UnknownNormalizationErrorModel
+   rxmc.likelihood_model.UnknownModelError
+   rxmc.likelihood_model.StudentTLikelihoodModel
+   rxmc.correlated_discrepancy_likelihood_model.SklearnKernelGPDiscrepancyModel
+
+Sampling
+--------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   rxmc.walker.Walker
+   rxmc.param_sampling.Sampler
+   rxmc.param_sampling.MetropolisHastingsSampler
+   rxmc.param_sampling.AdaptiveMetropolisSampler
+   rxmc.param_sampling.BatchedAdaptiveMetropolisSampler
+   rxmc.proposal.ProposalDistribution
+   rxmc.proposal.NormalProposalDistribution
+   rxmc.proposal.HalfNormalProposalDistribution
+   rxmc.proposal.LogspaceNormalProposalDistribution
+
+Sampling algorithms
+-------------------
+
+Low-level sampling functions used internally by the sampler classes.
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   rxmc.metropolis_hastings.metropolis_hastings
+   rxmc.adaptive_metropolis.adaptive_metropolis
+
+Domain-specific models
+----------------------
+
+Reaction-physics observation and model classes for elastic differential
+cross sections and isobaric-analog (p,n) cross sections.
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   rxmc.elastic_diffxs_observation.ElasticDifferentialXSObservation
+   rxmc.elastic_diffxs_model.ElasticDifferentialXSModel
+   rxmc.ias_pn_observation.IsobaricAnalogPNObservation
+   rxmc.ias_pn_model.IsobaricAnalogPNXSModel

docs/conf.py

@@ -0,0 +1,65 @@
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parents[1] / "src"))
+
+project = "rxmc"
+author = "Kyle Beyer"
+copyright = "2024, Kyle Beyer"
+
+try:
+    from rxmc.__version__ import version as release
+except ImportError:
+    release = "unknown"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "myst_nb",
+]
+
+html_theme = "pydata_sphinx_theme"
+html_theme_options = {
+    "github_url": "https://github.com/beykyle/rxmc",
+    "use_edit_page_button": False,
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+}
+html_static_path = ["_static"]
+
+# Napoleon settings
+napoleon_numpy_docstring = True
+napoleon_google_docstring = False
+napoleon_use_rtype = False
+napoleon_use_param = False
+
+# Autosummary
+autosummary_generate = True
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": False,
+    "show-inheritance": True,
+    "member-order": "bysource",
+}
+
+# myst-nb — notebooks are pre-executed; never re-run them during the build
+nb_execution_mode = "off"
+
+# MathJax — enable $...$ inline and \[...\] display delimiters used in docstrings
+mathjax3_config = {
+    "tex": {
+        "inlineMath": [["$", "$"], ["\\(", "\\)"]],
+        "displayMath": [["\\[", "\\]"]],
+    }
+}
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+}
+
+exclude_patterns = ["_build", "**.ipynb_checkpoints", "generated"]

docs/examples

@@ -0,0 +1 @@
+../examples