Migrate docs to Sphinx and Read the Docs

.github/workflows/docs.yml

@@ -3,11 +3,11 @@ name: Documentation
 on:
   push:
     branches: [main]
+  pull_request:
+    branches: [main]
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 jobs:
   build:
@@ -22,24 +22,9 @@ jobs:
 
       - name: Install dependencies
         run: |
+          python -m pip install --upgrade pip
           pip install -e ".[docs]"
 
-      - name: Build book
+      - name: Build docs
         run: |
-          jupyter-book build docs/
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: docs/_build/html
-
-  deploy:
-    needs: build
-    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
+          sphinx-build -W --keep-going -b html docs docs/_build/html

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

@@ -4,7 +4,7 @@ Multi-source microdata synthesis and survey reweighting.
 
 [![PyPI](https://img.shields.io/pypi/v/microplex.svg)](https://pypi.org/project/microplex/)
 [![Tests](https://github.com/CosilicoAI/microplex/actions/workflows/test.yml/badge.svg)](https://github.com/CosilicoAI/microplex/actions/workflows/test.yml)
-[![Docs](https://github.com/CosilicoAI/microplex/actions/workflows/docs.yml/badge.svg)](https://cosilicoai.github.io/microplex)
+[![Docs](https://readthedocs.org/projects/microplex/badge/?version=latest)](https://microplex.readthedocs.io/en/latest/)
 
 ## Overview
 
@@ -145,11 +145,11 @@ print(f"Using {stats['n_nonzero']} of {stats['n_records']} records")
 
 ## Documentation
 
-Full documentation at [cosilicoai.github.io/microplex](https://cosilicoai.github.io/microplex)
+Full documentation at [microplex.readthedocs.io](https://microplex.readthedocs.io/)
 
-- [Tutorial](https://cosilicoai.github.io/microplex/tutorial.html)
-- [API Reference](https://cosilicoai.github.io/microplex/api.html)
-- [Benchmarks](https://cosilicoai.github.io/microplex/benchmarks.html)
+- [Tutorial](https://microplex.readthedocs.io/en/latest/tutorial.html)
+- [API Reference](https://microplex.readthedocs.io/en/latest/api.html)
+- [Benchmarks](https://microplex.readthedocs.io/en/latest/notebooks/benchmarks.html)
 
 ## Benchmarks
 

docs/api.md

@@ -2,33 +2,29 @@
 
 ## Synthesizer
 
-```{eval-rst}
-.. autoclass:: microplex.Synthesizer
-   :members:
-   :undoc-members:
-   :show-inheritance:
+```{autoclass} microplex.Synthesizer
+:members:
+:undoc-members:
+:show-inheritance:
 ```
 
 ## Transforms
 
-```{eval-rst}
-.. automodule:: microplex.transforms
-   :members:
-   :undoc-members:
+```{automodule} microplex.transforms
+:members:
+:undoc-members:
 ```
 
 ## Flows
 
-```{eval-rst}
-.. automodule:: microplex.flows
-   :members:
-   :undoc-members:
+```{automodule} microplex.flows
+:members:
+:undoc-members:
 ```
 
 ## Discrete models
 
-```{eval-rst}
-.. automodule:: microplex.discrete
-   :members:
-   :undoc-members:
+```{automodule} microplex.discrete
+:members:
+:undoc-members:
 ```

docs/conf.py

@@ -0,0 +1,44 @@
+"""Sphinx configuration for the microplex documentation."""
+
+project = "microplex"
+author = "Cosilico"
+copyright = "2026, Cosilico"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
+]
+
+source_suffix = {
+    ".md": "markdown",
+    ".rst": "restructuredtext",
+}
+root_doc = "index"
+
+myst_enable_extensions = [
+    "colon_fence",
+    "dollarmath",
+]
+
+autodoc_member_order = "bysource"
+autosummary_generate = True
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+typehints_fully_qualified = False
+
+html_theme = "pydata_sphinx_theme"
+html_title = "microplex"
+html_theme_options = {
+    "github_url": "https://github.com/CosilicoAI/microplex",
+    "use_edit_page_button": True,
+}
+html_context = {
+    "github_user": "CosilicoAI",
+    "github_repo": "microplex",
+    "github_version": "main",
+    "doc_path": "docs",
+}

docs/index.md

@@ -0,0 +1,43 @@
+# microplex
+
+```{include} intro.md
+:start-after: "# microplex"
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Getting started
+
+tutorial
+notebooks/quickstart
+notebooks/benchmarks
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Methods
+
+reweighting
+sparse_calibration
+hierarchical_synthesis
+calibration_experiments
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Architecture and design
+
+unified_synthesis_architecture
+target_expansion_plan
+pe_household_structure
+pe_parity_status
+designs/household_transitions
+designs/multi_source_fusion
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Reference
+
+api
+```

docs/intro.md

@@ -102,8 +102,3 @@ synthetic = synth.generate(new_demographics)
 | Sparse reweighting | ✅ | ❌ |
 | Multi-source fusion | ✅ | ⚠️ |
 | Multiple synthesis methods | ✅ (QRF, QDNN, MAF) | ✅ (CART) |
-
-## Contents
-
-```{tableofcontents}
-```

pyproject.toml

@@ -79,18 +79,19 @@ benchmark = [
     "seaborn>=0.12",
 ]
 docs = [
-    "jupyter-book>=0.15,<2",
-    "sphinx>=6.0",
-    "myst-nb>=0.17",
-    "sphinx-autodoc-typehints>=1.23",
+    "sphinx>=7.2",
+    "myst-parser>=2.0",
+    "pydata-sphinx-theme>=0.15",
+    "sphinx-autodoc-typehints>=1.25",
+    "sphinx-copybutton>=0.5",
 ]
 all = [
     "microplex[dev,benchmark,docs,calibrate]",
 ]
 
 [project.urls]
 Homepage = "https://github.com/CosilicoAI/microplex"
-Documentation = "https://cosilicoai.github.io/microplex"
+Documentation = "https://microplex.readthedocs.io/"
 Repository = "https://github.com/CosilicoAI/microplex"
 
 [tool.hatch.build.targets.wheel]