📝 Fix near-empty API docs on Read the Docs - #623
Merged
Conversation
Read the Docs never installed the package, so autodoc could not import `bibtexparser` (pylatexenc missing) and every directive outside `bibtexparser.model` failed. The published API page listed 39 signatures, all `model.*` -- no parse_string, no Library, no BibtexFormat, no middlewares -- and customize.rst's cross-references resolved to nothing. - .readthedocs.yaml: install the package with its `docs` extra. The commented-out stub pointed at a docs/requirements.txt that does not exist, so uncommenting it as-is would have failed the build. - middlewares/__init__.py: add `__all__`. The module only re-exports, and autodoc skips imported members unless `__all__` names them. - entrypoint.py: blank line before the large-library note in write_file/write_string, which was glued onto the `:param:` field list and rendered as part of the last parameter. Sphinx now builds clean under -W: 116 signatures, 22 middleware classes, 27 resolved cross-references. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
1 participant
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.
Fixes #469.
The published v2.0.0 API page lists 39 signatures, all
bibtexparser.model.*— noparse_string, noLibrary, noBibtexFormat, no middlewares — andcustomize.rst's cross-references resolve to nothing.Cause 1:
.readthedocs.yamlnever installed the package, so autodoc failed to importbibtexparser(missingpylatexenc). The commented-out stub pointed at adocs/requirements.txtthat doesn't exist, so uncommenting it as-is would have failed the build. Now installs.[docs].Cause 2: persists even after Cause 1 is fixed —
bibtexparser/middlewares/__init__.pyonly re-exports, and autodoc skips imported members unless__all__names them. Added__all__.Also two blank lines in
entrypoint.py: the large-library note from #615 was glued onto the:param:field list and rendered as part of the last parameter. Only visible once autodoc could import the module.Sphinx builds clean under
-W. Tests: 2777 passed, 12 skipped.🤖 Generated with Claude Code