Fix RTD build (#540)

* 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

* 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

* 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

* 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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: mmore500

doc/conf.py

@@ -21,7 +21,6 @@
 import glob
 import os
 import sphinx_rtd_theme
-import subprocess
 import sys
 import textwrap
 
@@ -207,12 +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
-    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()]

doc/requirements.in

@@ -4,4 +4,4 @@ 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

doc/requirements.txt

@@ -1,8 +1,8 @@
 #
-# 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
@@ -11,16 +11,15 @@ babel==2.13.1
 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
@@ -49,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
@@ -69,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
@@ -91,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