Fix docs/PyPI version mismatch with versioned RTD builds

.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

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)

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")