Sphinx setup for MCGrad

.github/workflows/main.yaml

@@ -77,3 +77,38 @@ jobs:
       with:
         name: documentation
         path: website/build/
+
+  sphinx:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Cache pip packages
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-sphinx-${{ hashFiles('sphinx/requirements.txt', 'pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-sphinx-
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        pip install -r sphinx/requirements.txt
+
+    - name: Build Sphinx documentation
+      working-directory: ./sphinx
+      run: |
+        sphinx-build -b html source build/html
+
+    - name: Upload Sphinx documentation
+      uses: actions/upload-artifact@v4
+      with:
+        name: sphinx-documentation
+        path: sphinx/build/html/

.gitignore

@@ -12,6 +12,12 @@ website/build/
 website/.docusaurus/
 website/node_modules/
 
+# Sphinx build and artifacts
+sphinx/build/
+sphinx/source/_build/
+*.doctrees
+.buildinfo
+
 # Test coverage
 htmlcov/
 .coverage

.readthedocs.yaml

@@ -0,0 +1,34 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_install:
+      # Install the package in editable mode
+      - pip install -e .
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: sphinx/source/conf.py
+  fail_on_warning: false
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+    - requirements: sphinx/requirements.txt
+
+# Additional formats
+formats:
+  - pdf
+  - epub

README.md

@@ -17,7 +17,20 @@ Full documentation is available at: https://facebookincubator.github.io/MCGrad/
 
 - [Why MCBoost?](https://facebookincubator.github.io/MCGrad/docs/why-mcboost) - Learn about the benefits
 - [Quick Start](https://facebookincubator.github.io/MCGrad/docs/quickstart) - Get started quickly
-- [API Reference](https://facebookincubator.github.io/MCGrad/docs/api/methods) - Detailed API docs
+- [API Reference](https://mcgrad.readthedocs.io/) - Auto-generated API documentation from Python docstrings
+
+### Two Documentation Systems
+
+This project uses a dual documentation approach:
+
+1. **User Guide (Docusaurus)** - Available at https://facebookincubator.github.io/MCGrad/
+   - Getting started guides, tutorials, and conceptual documentation
+   - Built from the `website/` directory
+
+2. **API Reference (Sphinx)** - Available at https://multicalibration.readthedocs.io/
+   - Auto-generated from Python docstrings
+   - Detailed API documentation for all classes and functions
+   - Built from the `sphinx/` directory
 
 ## 🚀 Quick Start
 

scripts/test_docs.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# Script to test both Sphinx and Docusaurus documentation builds
+
+set -e  # Exit on error
+
+echo "🧪 Testing Documentation Builds"
+echo "================================"
+echo ""
+
+# Test 1: Build Sphinx documentation
+echo "📚 Step 1: Building Sphinx documentation..."
+echo "-------------------------------------------"
+cd sphinx
+
+# Check if sphinx-build is available
+if ! command -v sphinx-build &> /dev/null; then
+    echo "❌ sphinx-build not found. Installing dependencies..."
+    pip install -r requirements.txt
+fi
+
+# Build the docs
+echo "Building HTML docs..."
+make clean
+make html
+
+if [ $? -eq 0 ]; then
+    echo "✅ Sphinx build successful!"
+    echo "   Output: sphinx/build/html/index.html"
+else
+    echo "❌ Sphinx build failed!"
+    exit 1
+fi
+
+cd ..
+echo ""
+
+# Test 2: Build Docusaurus documentation
+echo "🌐 Step 2: Building Docusaurus website..."
+echo "-------------------------------------------"
+cd website
+
+# Check if npm is available
+if ! command -v npm &> /dev/null; then
+    echo "❌ npm not found. Please install Node.js"
+    exit 1
+fi
+
+# Install dependencies if needed
+if [ ! -d "node_modules" ]; then
+    echo "Installing npm dependencies..."
+    npm install
+fi
+
+# Build the docs
+echo "Building Docusaurus site..."
+npm run build
+
+if [ $? -eq 0 ]; then
+    echo "✅ Docusaurus build successful!"
+    echo "   Output: website/build/index.html"
+else
+    echo "❌ Docusaurus build failed!"
+    exit 1
+fi
+
+cd ..
+echo ""
+
+# Summary
+echo "🎉 All documentation builds successful!"
+echo "========================================"
+echo ""
+echo "To view the documentation:"
+echo ""
+echo "Sphinx (API Reference):"
+echo "  cd sphinx/build/html && python3 -m http.server 8000"
+echo "  Then open: http://localhost:8000"
+echo ""
+echo "Docusaurus (User Guide):"
+echo "  cd website && npm run serve"
+echo "  Then open: http://localhost:3000"
+echo ""
+echo "Note: The 'API Reference' link in Docusaurus points to"
+echo "https://mcgrad.readthedocs.io/ which won't work until"
+echo "you set up the project on ReadTheDocs."

sphinx/Makefile

@@ -0,0 +1,20 @@
+# Makefile for Sphinx 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
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

sphinx/README.md

@@ -0,0 +1,95 @@
+# Sphinx Documentation
+
+This directory contains the Sphinx-based API reference documentation for multicalibration, which is automatically generated from Python docstrings.
+
+## Building Documentation Locally
+
+### Prerequisites
+
+Install the required dependencies:
+
+```bash
+pip install -r requirements.txt
+# Also install the package itself
+pip install -e ..
+```
+
+### Building HTML Documentation
+
+```bash
+make html
+```
+
+The HTML documentation will be generated in `build/html/`.
+
+### Viewing the Documentation
+
+After building, you can view the documentation by opening `build/html/index.html` in your browser, or by running a local web server:
+
+```bash
+cd build/html
+python3 -m http.server 8000
+```
+
+Then navigate to http://localhost:8000
+
+### Other Build Formats
+
+Sphinx supports various output formats:
+
+```bash
+make pdf      # Build PDF documentation
+make epub     # Build ePub documentation
+make latexpdf # Build LaTeX PDF
+make clean    # Clean the build directory
+```
+
+## ReadTheDocs Integration
+
+This documentation is automatically built and hosted on ReadTheDocs whenever you push to the repository. The configuration is in `../.readthedocs.yaml`.
+
+Once set up on ReadTheDocs, the documentation will be available at:
+https://mcgrad.readthedocs.io/
+
+## Structure
+
+- `source/conf.py` - Sphinx configuration file
+- `source/index.rst` - Main documentation entry point
+- `source/api/` - API reference RST files that use autodoc to generate documentation from docstrings
+- `build/` - Generated documentation (not committed to git)
+
+## Updating API Documentation
+
+The API documentation is automatically generated from the Python source code docstrings.
+
+**Adding a new module:**
+
+1. Create `source/api/<module_name>.rst`:
+   ```rst
+   Module Name
+   ===========
+
+   .. automodule:: multicalibration.<module_name>
+      :members:
+      :undoc-members:
+      :show-inheritance:
+   ```
+
+   **That's it!** The `automodule` directive with `:members:` automatically
+   documents all classes and functions. No need to list them manually.
+
+2. Add it to `source/index.rst`:
+   ```rst
+   .. toctree::
+      :maxdepth: 2
+
+      api/methods
+      api/metrics
+      api/<module_name>  # Add here
+   ```
+
+The current setup uses:
+- **Google-style docstrings** (via `napoleon` extension)
+- **Automatic type hint extraction** (via `sphinx-autodoc-typehints`)
+- **ReadTheDocs theme** for consistent styling
+- **automodule directive** - automatically discovers and documents all public classes/functions

sphinx/requirements.txt

@@ -0,0 +1,3 @@
+sphinx>=7.0.0
+sphinx-rtd-theme>=2.0.0
+sphinx-autodoc-typehints>=1.25.0

sphinx/source/api/methods.rst

@@ -0,0 +1,7 @@
+Methods Module
+==============
+
+.. automodule:: multicalibration.methods
+   :members:
+   :undoc-members:
+   :show-inheritance:

sphinx/source/api/metrics.rst

@@ -0,0 +1,7 @@
+Metrics Module
+==============
+
+.. automodule:: multicalibration.metrics
+   :members:
+   :undoc-members:
+   :show-inheritance:

sphinx/source/api/plotting.rst

@@ -0,0 +1,7 @@
+Plotting Module
+===============
+
+.. automodule:: multicalibration.plotting
+   :members:
+   :undoc-members:
+   :show-inheritance:

sphinx/source/api/segmentation.rst

@@ -0,0 +1,7 @@
+Segmentation Module
+===================
+
+.. automodule:: multicalibration.segmentation
+   :members:
+   :undoc-members:
+   :show-inheritance:

sphinx/source/api/tuning.rst

@@ -0,0 +1,7 @@
+Tuning Module
+=============
+
+.. automodule:: multicalibration.tuning
+   :members:
+   :undoc-members:
+   :show-inheritance:

sphinx/source/api/utils.rst

@@ -0,0 +1,7 @@
+Utils Module
+============
+
+.. automodule:: multicalibration.utils
+   :members:
+   :undoc-members:
+   :show-inheritance: