From ec49b5822da6b4030bf645427db14499b03f4aac Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 9 Feb 2026 14:41:56 +0000
Subject: [PATCH 1/4] Fix RTD build: add setuptools dep and guard assets copy

The RTD build fails because pybtex imports pkg_resources, which requires
setuptools. Modern Python virtualenvs no longer include setuptools by
default. Add it as an explicit dependency.

Also guard the assets directory copy in conf.py with an existence check
to prevent the "cp: cannot stat 'assets'" error.

https://claude.ai/code/session_01T2FE3KjNU3yk8fjoc1WZvt
---
 doc/conf.py          | 9 +++++----
 doc/requirements.in  | 1 +
 doc/requirements.txt | 3 +++
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index 624924ec5d..4afab5e6d0 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -208,10 +208,11 @@
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 if on_rtd: # rtd doesn't run Makefile, so we have to copy assets ourself
-    subprocess.call(
-        'mkdir -p _build/html/docs/; cp -r assets _build/html/docs/',
-        shell=True,
-    )
+    if os.path.isdir('assets'):
+        subprocess.call(
+            'mkdir -p _build/html/docs/; cp -r assets _build/html/docs/',
+            shell=True,
+        )
 else:  # only import and set the theme if we're building docs locally
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
diff --git a/doc/requirements.in b/doc/requirements.in
index f45eb3d066..eef115c272 100644
--- a/doc/requirements.in
+++ b/doc/requirements.in
@@ -1,3 +1,4 @@
+setuptools
 sphinx==7.2.6
 sphinx-rtd-theme==2.0.0
 coverxygen==1.8.1
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 8293d91324..b6e0b353a5 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -6,6 +6,9 @@
 #
 alabaster==0.7.13
     # via sphinx
+setuptools>=69.0.0
+    # via pybtex (pkg_resources)
+    # via sphinx
 babel==2.13.1
     # via sphinx
 beautifulsoup4==4.12.2

From 4d6d798828980f9e3d1a75eac34a74fcce6dc50a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 9 Feb 2026 14:59:19 +0000
Subject: [PATCH 2/4] Pin setuptools<72 to retain pkg_resources module

setuptools 72+ removed pkg_resources as a bundled module. RTD upgrades
setuptools to 82.0.0 before installing our requirements, so the
>=69.0.0 constraint was already satisfied. Pinning <72 forces a
downgrade to a version that still includes pkg_resources, which pybtex
requires.

https://claude.ai/code/session_01T2FE3KjNU3yk8fjoc1WZvt
---
 doc/requirements.in  | 2 +-
 doc/requirements.txt | 3 +--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/doc/requirements.in b/doc/requirements.in
index eef115c272..cc85c5e8e1 100644
--- a/doc/requirements.in
+++ b/doc/requirements.in
@@ -1,4 +1,4 @@
-setuptools
+setuptools<72
 sphinx==7.2.6
 sphinx-rtd-theme==2.0.0
 coverxygen==1.8.1
diff --git a/doc/requirements.txt b/doc/requirements.txt
index b6e0b353a5..191c83a284 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -6,9 +6,8 @@
 #
 alabaster==0.7.13
     # via sphinx
-setuptools>=69.0.0
+setuptools>=69.0.0,<72
     # via pybtex (pkg_resources)
-    # via sphinx
 babel==2.13.1
     # via sphinx
 beautifulsoup4==4.12.2

From d32a9408a2cd1d2c6716bc3d22e9c67cc03903b2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Apr 2026 16:56:06 +0000
Subject: [PATCH 3/4] Remove dead assets copy block per review feedback

Delete the on_rtd branch that tried to copy a nonexistent assets
directory, and simplify to just `if not on_rtd`. Also remove the
now-unused subprocess import.

https://claude.ai/code/session_01T2FE3KjNU3yk8fjoc1WZvt
---
 doc/conf.py | 9 +--------
 1 file changed, 1 insertion(+), 8 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index 4afab5e6d0..30638cea61 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -21,7 +21,6 @@
 import glob
 import os
 import sphinx_rtd_theme
-import subprocess
 import sys
 import textwrap
 
@@ -207,13 +206,7 @@
 # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
-if on_rtd: # rtd doesn't run Makefile, so we have to copy assets ourself
-    if os.path.isdir('assets'):
-        subprocess.call(
-            'mkdir -p _build/html/docs/; cp -r assets _build/html/docs/',
-            shell=True,
-        )
-else:  # only import and set the theme if we're building docs locally
+if not on_rtd:  # only import and set the theme if we're building docs locally
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

From 4f473d34b7f85c858a3644798bd761a82e9448f9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Apr 2026 17:02:36 +0000
Subject: [PATCH 4/4] Bump sphinxcontrib-bibtex to 2.6.5 and regenerate
 requirements.txt

Replace the setuptools<72 pin with a sphinxcontrib-bibtex upgrade per
review feedback. Version 2.6.5 pulls in pybtex 0.26.0 which no longer
depends on pkg_resources, fixing the RTD build without needing to pin
setuptools.

https://claude.ai/code/session_01T2FE3KjNU3yk8fjoc1WZvt
---
 doc/requirements.in  |  3 +--
 doc/requirements.txt | 29 ++++++++++++-----------------
 2 files changed, 13 insertions(+), 19 deletions(-)

diff --git a/doc/requirements.in b/doc/requirements.in
index cc85c5e8e1..a94a59ecd4 100644
--- a/doc/requirements.in
+++ b/doc/requirements.in
@@ -1,8 +1,7 @@
-setuptools<72
 sphinx==7.2.6
 sphinx-rtd-theme==2.0.0
 coverxygen==1.8.1
 breathe==4.35.0
 myst-parser==2.0.0
 sphinx-tippy==0.4.1
-sphinxcontrib-bibtex==2.6.1
+sphinxcontrib-bibtex==2.6.5
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 191c83a284..7aa210d34f 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,28 +1,25 @@
 #
-# This file is autogenerated by pip-compile with Python 3.10
+# This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
-#    pip-compile doc/requirements.in
+#    pip-compile --output-file=doc/requirements.txt doc/requirements.in
 #
 alabaster==0.7.13
     # via sphinx
-setuptools>=69.0.0,<72
-    # via pybtex (pkg_resources)
 babel==2.13.1
     # via sphinx
 beautifulsoup4==4.12.2
     # via sphinx-tippy
 breathe==4.35.0
-    # via -r /tmp/requirements.in
+    # via -r doc/requirements.in
 certifi==2023.11.17
     # via requests
 charset-normalizer==3.3.2
     # via requests
 coverxygen==1.8.1
-    # via -r /tmp/requirements.in
+    # via -r doc/requirements.in
 docutils==0.20.1
     # via
-    #   -r /tmp/requirements.in
     #   breathe
     #   myst-parser
     #   pybtex-docutils
@@ -51,10 +48,10 @@ mdit-py-plugins==0.4.0
 mdurl==0.1.2
     # via markdown-it-py
 myst-parser==2.0.0
-    # via -r /tmp/requirements.in
+    # via -r doc/requirements.in
 packaging==23.2
     # via sphinx
-pybtex==0.24.0
+pybtex==0.26.0
     # via
     #   pybtex-docutils
     #   sphinxcontrib-bibtex
@@ -71,16 +68,14 @@ requests==2.31.0
     #   sphinx
     #   sphinx-tippy
 six==1.16.0
-    # via
-    #   latexcodec
-    #   pybtex
+    # via latexcodec
 snowballstemmer==2.2.0
     # via sphinx
 soupsieve==2.5
     # via beautifulsoup4
 sphinx==7.2.6
     # via
-    #   -r /tmp/requirements.in
+    #   -r doc/requirements.in
     #   breathe
     #   myst-parser
     #   sphinx-rtd-theme
@@ -93,13 +88,13 @@ sphinx==7.2.6
     #   sphinxcontrib-qthelp
     #   sphinxcontrib-serializinghtml
 sphinx-rtd-theme==2.0.0
-    # via -r /tmp/requirements.in
+    # via -r doc/requirements.in
 sphinx-tippy==0.4.1
-    # via -r /tmp/requirements.in
+    # via -r doc/requirements.in
 sphinxcontrib-applehelp==1.0.7
     # via sphinx
-sphinxcontrib-bibtex==2.6.1
-    # via -r /tmp/requirements.in
+sphinxcontrib-bibtex==2.6.5
+    # via -r doc/requirements.in
 sphinxcontrib-devhelp==1.0.5
     # via sphinx
 sphinxcontrib-htmlhelp==2.0.4