From a4740c10e461ce4c6da6fd2c4afaf60339c37570 Mon Sep 17 00:00:00 2001
From: igerber <isaac.gerber@gmail.com>
Date: Sun, 15 Feb 2026 17:17:51 -0500
Subject: [PATCH] Fix docs/PyPI version mismatch by building RTD docs from
 source (#146)

RTD now installs from the checked-out git ref instead of PyPI, so autodoc
always matches the code at that version. Adds Rust toolchain for maturin
build, consolidates docs deps into pyproject.toml, and adds a dev-version
warning banner for branch builds.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .readthedocs.yaml     | 12 ++++++++----
 CHANGELOG.md          |  3 +++
 docs/conf.py          | 21 +++++++++++++++++----
 docs/requirements.txt |  4 ----
 4 files changed, 28 insertions(+), 12 deletions(-)
 delete mode 100644 docs/requirements.txt

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 9ff330f9..3f52c420 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -3,18 +3,22 @@
 
 version: 2
 
-# Set the OS, Python version, and other tools you might need
 build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+    # Rust needed for maturin build. Pin for cache stability; update periodically.
+    rust: "1.82"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/conf.py
 
-# Install from PyPI (has pre-built wheels with Rust backend)
-# instead of building from source (which requires OpenBLAS)
+# Install from checked-out source so autodoc always matches the code at this ref.
+# Dependencies consolidated in pyproject.toml [project.optional-dependencies.docs].
 python:
   install:
-    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4bfcda5c..1c58de04 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- Fix docs/PyPI version mismatch (issue #146) — RTD now builds versioned docs from source
+
 ### Changed
 - Remove Rust outer-loop variance estimation for SyntheticDiD (placebo and bootstrap)
   - Fixes SE mismatch between pure Python and Rust backends (different RNG sequences)
diff --git a/docs/conf.py b/docs/conf.py
index 68ee03a2..5997b7e5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -4,10 +4,6 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import os
-import sys
-
-# Add the project root to the path for autodoc
-sys.path.insert(0, os.path.abspath(".."))
 
 import diff_diff
 
@@ -16,6 +12,7 @@
 copyright = "2026, diff-diff contributors"
 author = "diff-diff contributors"
 release = diff_diff.__version__
+version = ".".join(diff_diff.__version__.split(".")[:2])
 
 # -- General configuration ---------------------------------------------------
 extensions = [
@@ -76,6 +73,22 @@
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
 }
 
+# -- ReadTheDocs version-aware banner ----------------------------------------
+# Shows a warning on development builds so users know they may be reading
+# docs for unreleased features. Only activates on RTD (not local builds).
+rtd_version = os.environ.get("READTHEDOCS_VERSION", "")
+rtd_version_type = os.environ.get("READTHEDOCS_VERSION_TYPE", "")
+
+if rtd_version == "latest" or rtd_version_type == "branch":
+    rst_prolog = """
+.. warning::
+
+   This documentation is for the **development version** of diff-diff.
+   It may describe features not yet available in the latest PyPI release.
+   For stable documentation, use the version selector (bottom-left) to switch to **stable**.
+
+"""
+
 # -- Custom CSS --------------------------------------------------------------
 def setup(app):
     app.add_css_file("custom.css")
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index bf0422d4..00000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-# Documentation build requirements
-diff-diff>=2.0.0
-sphinx>=6.0
-sphinx-rtd-theme>=1.0