Unpin the docs toolchain so Read the Docs can build again - #115
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The Read the Docs build fails before it reads a single page:
Cause
doc/doc_requirements.txtpinned Sphinx 2.2.0 along with its entire 2019 dependencyset. Sphinx 2.2.0 imports
pkg_resources, which setuptools removed in 81.0. Nothing inthe 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- addingdwca.star_recordto the API reference (new in 0.17.0)started rendering its docstring, which attached a trailing
sdirectly 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 foundthrough its entry point, so
html_theme_pathand the import go away.doc/conf.py-html_static_pathpointed atdoc/_static, which does not exist.Verification
Built with the exact command Read the Docs runs, in a virtualenv containing only
doc_requirements.txtand without the package installed, matching the RTD environment: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 inapi.html),StarRecordIterator,skip_metadata,get_corerow_by_position, and no references to thelong-removed
get_row_by_index. Test suite unchanged at 222 passing.One thing this does NOT fix
Read the Docs builds
stablefrom the latest tag, which isv0.17.0and predates thiscommit. Merging this repairs the
latestbuild immediately, butstablewill keep failinguntil 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.0currently matches exactly what ispublished on PyPI.