Add Sphinx docs with GitHub Pages deploy

.github/workflows/docs.yaml

@@ -0,0 +1,72 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yaml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: uv sync --group docs
+
+      - name: Build HTML docs
+        run: uv run sphinx-build -W --keep-going -b html docs/source docs/build/html
+
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+      - name: Upload preview artifact
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-docs
+          path: docs/build/html/
+          retention-days: 7
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -42,6 +42,8 @@ nosetests.xml
 
 # Sphinx documentation
 docs/_build/
+docs/build/
+docs/source/_autosummary/
 
 verification.ipynb
 

README.md

@@ -14,6 +14,9 @@ Run evaluation pipelines for data-driven weather models built with [Anemoi](http
 2. [Credentials setup](#credentials-setup)
 3. [Workspace setup](#workspace-setup)
 
+For the rendered developer documentation, see the Sphinx site under `docs/`.
+Build it locally with `uv sync --group docs && sphinx-build -b html docs/source docs/build/html`.
+
 ## Features:
 - [Experiments](#experiment): compare model performance via standard and diagnostic verification
 - [Showcasing](#showcase): produce visual material for specific events

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+.PHONY: help Makefile clean livehtml
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -rf "$(BUILDDIR)" "$(SOURCEDIR)/_autosummary"
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,29 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found.
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_static/custom.css

@@ -0,0 +1,17 @@
+/* Widen the content column so wide rule tables and code samples don't wrap. */
+.wy-nav-content {
+    max-width: 1100px;
+}
+
+/* Slightly tighten table cell padding for the rule reference tables. */
+.rst-content table.docutils td,
+.rst-content table.docutils th {
+    padding: 6px 10px;
+}
+
+/* Highlight inline literal code (filenames, run_ids) more clearly. */
+.rst-content code.literal {
+    background: #f6f8fa;
+    border: 1px solid #e1e4e8;
+    color: #24292e;
+}

docs/source/conf.py

@@ -0,0 +1,97 @@
+"""Sphinx configuration for the EvalML documentation."""
+
+from __future__ import annotations
+
+import sys
+from importlib import metadata
+from pathlib import Path
+
+# Project layout: docs/source/conf.py -> repo root is two parents up.
+REPO_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO_ROOT / "src"))
+
+# -- Project information -----------------------------------------------------
+
+project = "EvalML"
+author = "MeteoSwiss"
+copyright = f"%Y, {author}"
+
+try:
+    release = metadata.version("evalml")
+except metadata.PackageNotFoundError:
+    release = "0.0.0"
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "sphinx_click",
+]
+
+source_suffix = {
+    ".md": "markdown",
+    ".rst": "restructuredtext",
+}
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "linkify",
+    "substitution",
+    "tasklist",
+]
+myst_heading_anchors = 3
+
+autosummary_generate = False
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+
+# Napoleon picks up both Google- and NumPy-style docstrings present in src/.
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+
+# Imports that may not be available on the docs builder (heavy scientific stack).
+# We don't currently mock anything because RTD installs the project, but if a
+# build env can't pull cartopy/earthkit, add modules here.
+autodoc_mock_imports: list[str] = []
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
+    "pydantic": ("https://docs.pydantic.dev/latest/", None),
+    "click": ("https://click.palletsprojects.com/en/stable/", None),
+    "snakemake": ("https://snakemake.readthedocs.io/en/stable/", None),
+}
+
+templates_path = ["_templates"]
+exclude_patterns: list[str] = []
+
+# Keep the first build green; flip to True once docstring coverage improves.
+nitpicky = False
+
+# -- HTML output -------------------------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_title = f"EvalML {version}"
+
+html_theme_options = {
+    "navigation_depth": 4,
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "titles_only": False,
+}

docs/source/contributing/ci.md

@@ -0,0 +1,95 @@
+# CI
+
+EvalML's GitHub Actions live under `.github/workflows/`.
+
+## `ci.yaml`
+
+The main CI workflow runs on every push to `main` and every PR targeting
+`main`.
+
+### Job: `test`
+
+Matrix:
+
+- `os`: `ubuntu-latest`
+- `python-version`: `3.11`, `3.12`, `3.13`
+- `anemoi-dev`: `false` today; the leg that's `true` would install
+  `anemoi-inference` and `anemoi-datasets` from `main`. Keep an eye on
+  this if you change anything inference-adjacent.
+
+Steps:
+
+1. `astral-sh/setup-uv@v2` (with caching).
+2. `actions/setup-python@v5` to install the matrix Python.
+3. `uv sync --all-extras --dev` to install the project + dev tools +
+   the `kerchunk` extra.
+4. `uv run pytest tests/`.
+
+### Job: `lint`
+
+Runs `pre-commit run --all-files --verbose`, which exercises:
+
+- `trailing-whitespace`, `end-of-file-fixer`.
+- `ruff` (auto-fix) and `ruff-format`.
+- `snakefmt workflow/`.
+- The local `pydantic-schema` hook that regenerates
+  `workflow/tools/config.schema.json` and asserts no diff.
+
+## `docs.yaml`
+
+Triggered on push to `main`, on PR open/reopen/sync/close, and via
+`workflow_dispatch`. It has three jobs:
+
+### `build`
+
+1. Installs `uv` and Python 3.12.
+2. Runs `uv sync --group docs`.
+3. Builds the docs with
+   `sphinx-build -W --keep-going -b html docs/source docs/build/html`.
+4. Uploads the result as a workflow artifact (`html-docs`, 7-day
+   retention) so reviewers can download the rendered HTML and so the
+   deploy jobs can pick it up.
+
+`-W` turns warnings into errors, so any broken cross-reference,
+malformed directive, or missing module fails the build. If the build
+fails on something genuinely unfixable on the docs side (e.g. a heavy
+runtime dependency that can't be installed in CI), add the offending
+import to `autodoc_mock_imports` in `docs/source/conf.py`.
+
+The build is skipped on PR close — only the preview-cleanup needs to
+run at that point.
+
+### `deploy-main`
+
+Only runs on push to `main`. Downloads the `html-docs` artifact and
+publishes it to the root of the `gh-pages` branch via
+[`JamesIves/github-pages-deploy-action`](https://github.com/JamesIves/github-pages-deploy-action).
+The `clean-exclude: pr-preview/` setting preserves PR preview
+directories so a main-branch deploy doesn't wipe open previews.
+
+### `preview`
+
+Runs on every PR event. Uses
+[`rossjrw/pr-preview-action`](https://github.com/rossjrw/pr-preview-action)
+to deploy the built site to
+`gh-pages/pr-preview/pr-<number>/`, and to remove that directory when
+the PR is closed. The action also posts and updates a comment on the
+PR with the preview URL.
+
+## GitHub Pages
+
+The rendered docs are hosted on GitHub Pages from the `gh-pages` branch.
+To enable Pages on a fresh fork or new repository:
+
+1. Go to **Settings → Pages**.
+2. Under **Build and deployment** → **Source**, select
+   **Deploy from a branch**.
+3. Set **Branch** to `gh-pages` and **Folder** to `/ (root)`.
+4. Save.
+
+The first push to `main` after that publishes the site at
+`https://<owner>.github.io/<repo>/`. PR previews appear at
+`https://<owner>.github.io/<repo>/pr-preview/pr-<number>/`.
+
+Note: the `gh-pages` branch is created automatically by the deploy
+action on the first run; you don't need to create it manually.