Unpin the docs toolchain so Read the Docs can build again

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
 # "<project> v<release> 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.

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

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,