Add sphinx docs

.github/workflows/rtd-preview.yml

@@ -0,0 +1,30 @@
+name: Read the Docs PR preview
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+    # Only fire when something that could change the docs build is touched.
+    paths:
+      - "docs/**"
+      - ".readthedocs.yaml"
+      - "conda_envs/environment-docs.yaml"
+      - "ptgp/**"
+      - "pyproject.toml"
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          # Project slug as configured on Read the Docs. Verify this matches
+          # the slug shown in the RTD project URL
+          # (https://readthedocs.org/projects/<slug>/) once the project is
+          # imported there.
+          project-slug: "ptgp"

.gitignore

@@ -188,3 +188,4 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 .idea/
+/docs/source/

.pre-commit-config.yaml

@@ -28,3 +28,12 @@ repos:
     - id: no-print-statements
       files: ^ptgp/
       exclude: ^ptgp/_cli\.py$
+
+- repo: local
+  hooks:
+    - id: check-kernel-gallery
+      name: check covariance gallery covers every public kernel
+      entry: python scripts/check_kernel_gallery.py
+      language: system
+      pass_filenames: false
+      files: ^(ptgp/kernels/|docs/sphinxext/generate_kernel_gallery\.py$)

.readthedocs.yaml

@@ -0,0 +1,18 @@
+version: 2
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: false
+
+conda:
+  environment: conda_envs/environment-docs.yaml
+
+python:
+  install:
+    - method: pip
+      path: .
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "mambaforge-latest"

conda_envs/environment-docs.yaml

@@ -0,0 +1,36 @@
+name: ptgp-docs
+channels:
+    - conda-forge
+dependencies:
+    - python>=3.12
+    # Runtime deps: autodoc imports ptgp, so the full runtime stack has to
+    # be in scope.
+    - jax
+    - jaxlib
+    - optax
+    - numpy
+    - scipy
+    - libblas=*=*mkl
+    - mkl-service
+    - pymc
+    - matplotlib
+    # Docs build deps.
+    - ipython
+    - jupyter
+    - sphinx>=7
+    - pydata-sphinx-theme
+    - myst-nb
+    - numpydoc
+    - sphinx-copybutton
+    - sphinx-design
+    - sphinx-codeautolink
+    - sphinx-sitemap
+    - sphinx-notfound-page
+    - sphinx-autobuild
+    - jupyter-sphinx
+    - sphinxcontrib-bibtex
+    - pip
+    - pip:
+        - git+https://github.com/pymc-devs/pytensor@main
+        # ptgp itself so autodoc resolves the current source tree.
+        - -e ..

conda_envs/environment.yaml

@@ -22,6 +22,18 @@ dependencies:
     - pytest
     - mypy
     - polars
-    - pymc
+    # Docs tooling — kept in sync with conda_envs/environment-docs.yaml so
+    # `make html` works in the dev env without an extra install step.
+    - sphinx>=7
+    - pydata-sphinx-theme
+    - myst-nb
+    - numpydoc
+    - sphinx-copybutton
+    - sphinx-design
+    - sphinx-codeautolink
+    - sphinx-sitemap
+    - sphinx-notfound-page
+    - jupyter-sphinx
+    - sphinxcontrib-bibtex
     - arviz
     - pip

docs/.gitignore

@@ -0,0 +1,25 @@
+# Sphinx build output
+build/
+jupyter_execute/
+
+# Python cache
+__pycache__/
+*.pyc
+
+# Autosummary-generated stubs (one .rst per object, regenerated on build)
+source/api/generated/
+source/api/**/generated/
+source/api/**/classmethods/
+
+# Notebook gallery artifacts written by docs/sphinxext/generate_gallery.py
+source/examples/gallery.rst
+source/examples/examples/
+source/examples/introductory/
+source/examples/advanced/
+source/examples/case_study/
+source/_thumbnails/
+
+# Covariance gallery artifacts written by
+# docs/sphinxext/generate_kernel_gallery.py
+source/kernels/gallery.rst
+source/kernels/img/

docs/Makefile

@@ -0,0 +1,36 @@
+# Minimal Makefile for Sphinx documentation.
+# Mirrors the standard sphinx-quickstart output.
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+.PHONY: help clean html show livehtml linkcheck Makefile
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -rf "$(BUILDDIR)"
+	rm -rf "$(SOURCEDIR)"/api/generated
+	rm -rf "$(SOURCEDIR)"/api/*/generated
+	rm -rf "$(SOURCEDIR)"/_thumbnails
+	rm -f  "$(SOURCEDIR)"/examples/gallery.rst
+	rm -rf "$(SOURCEDIR)"/kernels/img
+	rm -f  "$(SOURCEDIR)"/kernels/gallery.rst
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+show: html
+	@open "$(BUILDDIR)/html/index.html"
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+linkcheck:
+	@$(SPHINXBUILD) -M linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(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. Install Sphinx, then re-run.
+	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/_templates/autosummary/class.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   {% if methods %}
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: classmethods
+
+   {% for item in methods %}
+   {%- if item not in inherited_members %}
+      {{ objname }}.{{ item }}
+   {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+   {%- if item not in inherited_members %}
+      ~{{ name }}.{{ item }}
+   {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/api.rst

@@ -0,0 +1,20 @@
+.. _api:
+
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    api/gp
+    api/kernels
+    api/likelihoods
+    api/mean
+    api/inducing
+    api/inducing_fourier
+    api/objectives
+    api/conditionals
+    api/kl
+    api/optim
+    api/utils

docs/source/api/conditionals.rst

@@ -0,0 +1,13 @@
+Conditionals
+============
+
+.. currentmodule:: ptgp.conditionals
+
+Symbolic predictive conditionals used by the variational GP models.
+
+.. autosummary::
+    :toctree: generated/
+
+    conditional_whitened
+    conditional_unwhitened
+    base_conditional

docs/source/api/gp.rst

@@ -0,0 +1,13 @@
+GP Models
+=========
+
+.. currentmodule:: ptgp.gp
+
+.. autosummary::
+    :toctree: generated/
+
+    Unapproximated
+    VFE
+    SVGP
+    VariationalParams
+    init_variational_params

docs/source/api/inducing.rst

@@ -0,0 +1,35 @@
+Inducing Points
+===============
+
+.. currentmodule:: ptgp.inducing
+
+Inducing variables
+------------------
+
+.. autosummary::
+    :toctree: generated/
+
+    InducingVariables
+    Points
+
+Initialization strategies
+-------------------------
+
+.. autosummary::
+    :toctree: generated/
+
+    random_subsample_init
+    kmeans_init
+    greedy_variance_init
+
+Diagnostics
+-----------
+
+.. autosummary::
+    :toctree: generated/
+
+    KernelHealthDiagnostics
+    RandomSubsampleDiagnostics
+    KMeansDiagnostics
+    GreedyVarianceDiagnostics
+    compute_inducing_diagnostics

docs/source/api/inducing_fourier.rst

@@ -0,0 +1,9 @@
+Fourier Features
+================
+
+.. currentmodule:: ptgp.inducing_fourier
+
+.. autosummary::
+    :toctree: generated/
+
+    FourierFeatures1D

docs/source/api/kernels.rst

@@ -0,0 +1,51 @@
+Kernels
+=======
+
+.. currentmodule:: ptgp.kernels
+
+Base
+----
+
+.. autosummary::
+    :toctree: generated/
+
+    Kernel
+
+Stationary
+----------
+
+.. autosummary::
+    :toctree: generated/
+
+    ExpQuad
+    Matern52
+    Matern32
+    Matern12
+
+Non-stationary
+--------------
+
+.. autosummary::
+    :toctree: generated/
+
+    Gibbs
+    RandomWalk
+    WarpedInput
+
+Categorical
+-----------
+
+.. autosummary::
+    :toctree: generated/
+
+    Overlap
+    LowRankCategorical
+
+Composition
+-----------
+
+.. autosummary::
+    :toctree: generated/
+
+    SumKernel
+    ProductKernel