Contributing to MAPIE Documentation¶

For coding contributions, see the MAPIE contribution guidelines.

This guide explains how to add, edit, and preview MAPIE's documentation built with MkDocs Material.

Prerequisites¶

Install the documentation dependencies:

pip install -e ".[docs]"

Local Preview¶

Start the development server:

mkdocs serve -a 127.0.0.1:8787

Open http://127.0.0.1:8787 in your browser. Pages reload automatically when you save changes.

Project Structure¶

mkdocs.yml                  # Main configuration
doc/
├── index.md                # Homepage
├── content/                # Handwritten documentation
│   ├── getting-started/    # Getting started guides
│   ├── conformal-prediction/
│   ├── risk-control/
│   ├── calibration/
│   ├── exchangeability-testing/
│   ├── all-examples/
│   └── contributing-docs.md
├── generated/              # Gallery output
├── images/                 # Images used in documentation
├── stylesheets/extra.css   # Custom CSS overrides
├── javascripts/mathjax.js  # MathJax configuration
└── hooks/                  # MkDocs build and API reference hooks
examples/
├── regression/             # Gallery example scripts
├── classification/
├── calibration/
├── risk_control/
└── conditional_cp/

Adding a New Documentation Page¶

1. Create the Markdown File¶

Create a .md file in the appropriate section under doc/content/. For example, to add a new conformal-prediction theory page:

doc/content/conformal-prediction/my-new-topic.md

Write your content using standard Markdown:

# My New Topic

Introduction text here.

## Section Title

Content with **bold**, `code`, and math: $\alpha = 0.1$.

$$
\hat{C}_n(X_{n+1}) = \hat{\mu}(X_{n+1}) \pm \hat{q}_{1-\alpha}\{|Y_i - \hat{\mu}(X_i)|\}
$$

!!! note
    Use admonitions for important information.

Edit mkdocs.yml and add your page to the nav section:

nav:
  - Conformal Prediction:
    - Theory:
      - Foundations: content/conformal-prediction/theory.md
      - My New Topic: content/conformal-prediction/my-new-topic.md   # ← add here

3. Add Images¶

Place images in doc/images/ and reference them:

![Description](../../images/my-image.png)

Adding a New Gallery Example¶

Gallery examples are Python scripts in examples/ that are automatically rendered as interactive documentation pages by the mkdocs-gallery plugin.

1. Create the Example Script¶

Create a .py file in the appropriate subdirectory. The filename must start with plot_:

examples/regression/1-quickstart/plot_my_example.py

2. Script Structure¶

Gallery scripts use a specific format with docstrings and comment blocks:

"""
# Example Title

Brief description of what this example demonstrates.
"""

##############################################################################
# Section heading as a comment block.
# This text will be rendered as Markdown.

import numpy as np
from mapie.regression import SplitConformalRegressor

##############################################################################
# Another explanatory section.
# You can use **Markdown** formatting here.
#
# - Bullet points work
# - Math works: $\alpha = 0.1$

# Code that generates a plot will be shown with its output
import matplotlib.pyplot as plt

plt.figure()
plt.plot([1, 2, 3], [1, 4, 9])
plt.title("My Plot")
plt.show()

Key rules:

Title block: The first triple-quoted docstring becomes the page title (use # Markdown heading).
Comment blocks: Lines starting with # followed by # separators are rendered as Markdown text sections.
Code blocks: Regular Python code is displayed as executable code with output.
Plots: Any matplotlib figure created will be captured and displayed.

3. Add a Subsection Directory (if needed)¶

If you're creating a new subsection (e.g., 3-scientific-articles/), add a README.md in the directory:

examples/regression/3-scientific-articles/README.md

# Scientific Articles

Examples reproducing results from scientific papers.

4. Add a New Top-Level Gallery Section (if needed)¶

To add an entirely new gallery section (e.g., examples/time_series/):

Create the directory with subdirectories:

 examples/time_series/
 examples/time_series/README.md
 examples/time_series/1-quickstart/
 examples/time_series/1-quickstart/README.md
 examples/time_series/1-quickstart/plot_example.py

Register it in mkdocs.yml under the gallery plugin:

 plugins:
   - gallery:
       examples_dirs:
         - examples/regression
         - examples/time_series       # ← add here
       gallery_dirs:
         - doc/generated/regression
         - doc/generated/time_series  # ← add here

Add a navigation entry in the relevant topic section and add the new gallery link to doc/content/all-examples/index.md:
```
 nav:
   - Time Series:
     - Examples: generated/time_series  # ← add here
```

Editing API Documentation¶

API pages and their navigation are generated at build time by doc/hooks/api_reference.py. The hook uses mkdocstrings to render the Python docstrings.

How It Works¶

The hook creates virtual Markdown pages containing directives like:

::: mapie.regression.SplitConformalRegressor

The generated pages exist only during the MkDocs build, so running the documentation does not modify the working tree.

Adding a Public Class or Function¶

Add the object to the module's __all__ list when the module defines one. The generator treats __all__ as authoritative.
In modules without __all__, define the public class or function at module level without a leading underscore. Objects imported from another module are ignored.
Build the documentation. The object is automatically added to its API page, the overview, and the left navigation.

Internal objects whose names cannot yet be made private are listed in the generator's narrow INTERNAL_SYMBOLS exclusion map. New metric submodules should also be exported from mapie.metrics.__all__; each exported submodule gets its own generated section. Optional metric modules that cannot be imported by the base installation belong in OPTIONAL_METRIC_MODULES instead.

Adding an entirely new API category still requires one page-level entry in api_pages(), where its title, description, and source module are declared.

Docstring Format¶

MAPIE uses numpy-style docstrings. Use single backticks for inline code:

def my_method(self, X, alpha=0.1):
    """Compute prediction intervals.

    Parameters
    ----------
    X : ArrayLike of shape (n_samples, n_features)
        Input data.

    alpha : float
        Significance level. Defaults to `0.1`.

    Returns
    -------
    prediction_intervals : NDArray of shape (n_samples, 2)
        Lower and upper bounds of the prediction intervals.
    """

Using Math Equations¶

MathJax is configured for rendering LaTeX math.

Inline: $\alpha$ renders as $\alpha$

Block:

$$
\hat{q}_{1-\alpha} = \text{Quantile}\left(1 - \alpha; \frac{1}{n} \sum_{i=1}^{n} \delta_{s_i}\right)
$$

Using Admonitions¶

MkDocs Material supports various admonition types:

!!! note "Optional Title"
    Note content here.

!!! warning
    Warning content here.

!!! example
    Example content here.

!!! tip
    Tip content here.

Building for Production¶

Build the static site:

mkdocs build

The output goes to site/ (gitignored). The GitHub Actions workflow in .github/workflows/deploy-docs.yml handles deployment automatically on push to main.