From ba38f54bfe9f256c6ee3cab7b17a10c21c38f656 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicolas=20No=C3=A9?= Date: Wed, 29 Jul 2026 11:01:34 +0200 Subject: [PATCH] Unpin the docs toolchain so Read the Docs can build again doc_requirements.txt pinned Sphinx 2.2.0 and its whole 2019 dependency set. Sphinx 2.2.0 imports pkg_resources, which setuptools removed in 81.0, so the Read the Docs build failed before reading a single page: from pkg_resources import iter_entry_points ModuleNotFoundError: No module named 'pkg_resources' Pinning every transitive dependency is what let this rot unnoticed for years, so the file now lists only the two direct dependencies with lower bounds. Also clears the three warnings the build emitted, one of which was newly introduced by adding dwca.star_record to the API reference: its docstring referred to the CSVDataFile class with a trailing "s" attached directly to the inline markup, which is invalid reStructuredText. It is now a proper :class: cross-reference. Verified by building with the exact Read the Docs command, in a virtualenv holding only doc_requirements.txt and without the package installed: build succeeded, zero warnings, and autodoc still picks up iter_terms, StarRecordIterator and skip_metadata. --- doc/conf.py | 9 +++++---- doc/doc_requirements.txt | 32 ++++++++------------------------ dwca/star_record.py | 2 +- 3 files changed, 14 insertions(+), 29 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 8e0ec0a..6f85108 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -10,7 +10,6 @@ # serve to show the default. import sys, os -import sphinx_rtd_theme # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -103,8 +102,8 @@ # documentation. # html_theme_options = {} -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +# The theme is discovered through its entry point; sphinx_rtd_theme.get_html_theme_path() +# was deprecated and setting html_theme_path is no longer needed. # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -125,7 +124,9 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] +# No custom static assets, and pointing at a directory that does not exist makes Sphinx +# warn on every build. +html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/doc/doc_requirements.txt b/doc/doc_requirements.txt index 23186a2..c6251b4 100644 --- a/doc/doc_requirements.txt +++ b/doc/doc_requirements.txt @@ -1,24 +1,8 @@ -alabaster==0.7.12 -Babel==2.9.1 -certifi==2019.6.16 -chardet==3.0.4 -docutils==0.15.2 -idna==2.8 -imagesize==1.1.0 -Jinja2==2.11.3 -MarkupSafe==1.1.1 -packaging==19.2 -Pygments==2.7.4 -pyparsing==2.4.2 -pytz==2019.2 -requests==2.22.0 -six==1.12.0 -snowballstemmer==1.9.1 -Sphinx==2.2.0 -sphinx-rtd-theme==0.4.3 -sphinxcontrib-applehelp==1.0.1 -sphinxcontrib-devhelp==1.0.1 -sphinxcontrib-htmlhelp==1.0.2 -sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-qthelp==1.0.2 -sphinxcontrib-serializinghtml==1.1.3 +# Only the direct dependencies are listed. This file used to pin every transitive +# dependency at its 2019 version, which is what eventually broke the Read the Docs build: +# Sphinx 2.2.0 imports pkg_resources, and setuptools removed it in 81.0, so the build died +# with ModuleNotFoundError before it read a single page. +# +# Lower bounds only, so a routine dependency update cannot silently rot the docs again. +Sphinx>=7 +sphinx-rtd-theme>=2 diff --git a/dwca/star_record.py b/dwca/star_record.py index a3ff49d..71f869c 100644 --- a/dwca/star_record.py +++ b/dwca/star_record.py @@ -6,7 +6,7 @@ class StarRecordIterator(object): """Object used to iterate over multiple DWCA-files joined on the coreid - :param files_to_join: a list of the `dwca.files.CSVDataFile`s we'd like to join. + :param files_to_join: a list of the :class:`dwca.files.CSVDataFile` objects to join. May or may not include the core file (the core is not treated in a special way) :param how: indicates the type of join. "inner" and "outer" correspond vaguely to inner and full joins. The outer join includes rows that don't match on all files,