Skip to content

Unpin the docs toolchain so Read the Docs can build again - #115

Merged
niconoe merged 1 commit into
mainfrom
docs-sphinx-modernise
Jul 29, 2026
Merged

Unpin the docs toolchain so Read the Docs can build again#115
niconoe merged 1 commit into
mainfrom
docs-sphinx-modernise

Conversation

@niconoe

@niconoe niconoe commented Jul 29, 2026

Copy link
Copy Markdown
Member

The Read the Docs build fails before it reads a single page:

from pkg_resources import iter_entry_points
ModuleNotFoundError: No module named 'pkg_resources'

Cause

doc/doc_requirements.txt pinned Sphinx 2.2.0 along with its entire 2019 dependency
set. Sphinx 2.2.0 imports pkg_resources, which setuptools removed in 81.0. Nothing in
the repository changed to cause this - the pins simply rotted until Read the Docs rebuilt the
environment, which the 0.17.0 release triggered.

Pinning every transitive dependency is what let it rot silently for six years, so this drops
to the two direct dependencies with lower bounds only.

Also fixes the build warnings

The build emitted three, and one of them was introduced by this release:

  • dwca/star_record.py - adding dwca.star_record to the API reference (new in 0.17.0)
    started rendering its docstring, which attached a trailing s directly to inline markup.
    That is invalid reStructuredText. Now a proper :class: cross-reference.
  • doc/conf.py - sphinx_rtd_theme.get_html_theme_path() is deprecated; the theme is found
    through its entry point, so html_theme_path and the import go away.
  • doc/conf.py - html_static_path pointed at doc/_static, which does not exist.

Verification

Built with the exact command Read the Docs runs, in a virtualenv containing only
doc_requirements.txt and without the package installed, matching the RTD environment:

python -m sphinx -T -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html

build succeeded, zero warnings. Resolved to Sphinx 9.0.4 and sphinx-rtd-theme 3.1.0.

Autodoc still picks up the API surface: iter_terms (9 mentions in api.html),
StarRecordIterator, skip_metadata, get_corerow_by_position, and no references to the
long-removed get_row_by_index. Test suite unchanged at 222 passing.

One thing this does NOT fix

Read the Docs builds stable from the latest tag, which is v0.17.0 and predates this
commit. Merging this repairs the latest build immediately, but stable will keep failing
until a tag exists that contains it. That needs either a 0.17.1 release or moving the tag -
a decision worth making deliberately, since v0.17.0 currently matches exactly what is
published on PyPI.

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.
@niconoe
niconoe merged commit 29d889d into main Jul 29, 2026
21 checks passed
@niconoe
niconoe deleted the docs-sphinx-modernise branch July 29, 2026 09:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant