From 7202607a824620c17ca9ca12e9948e87d331071d Mon Sep 17 00:00:00 2001 From: Michael Weiss Date: Thu, 10 Sep 2026 22:02:49 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Fix=20near-empty=20API=20docs=20?= =?UTF-8?q?on=20Read=20the=20Docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .readthedocs.yaml | 14 +++++++++----- bibtexparser/entrypoint.py | 2 ++ bibtexparser/middlewares/__init__.py | 28 ++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 5 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0ff55962..8b4a0c59 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -15,8 +15,12 @@ build: sphinx: configuration: docs/source/conf.py -# We recommend specifying your dependencies to enable reproducible builds: -# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt +# Install the package itself (and its runtime dependencies) so that autodoc can +# import it; without this, every autodoc directive outside bibtexparser.model +# fails on the missing pylatexenc import and the API page comes out near-empty. +python: + install: + - method: pip + path: . + extra_requirements: + - docs diff --git a/bibtexparser/entrypoint.py b/bibtexparser/entrypoint.py index c9979462..8a093f79 100644 --- a/bibtexparser/entrypoint.py +++ b/bibtexparser/entrypoint.py @@ -330,6 +330,7 @@ def write_file( Only applicable if `unparse_stack` is None. :param bibtex_format: Customized BibTeX format to use (optional). :param encoding: Encoding of the .bib file. Default encoding is ``"UTF-8"``. + Writing a library with at least ``LARGE_LIBRARY_WARNING_THRESHOLD`` blocks logs a warning if the unparse stack deep-copies blocks (middlewares with ``allow_inplace_modification=False``), as that is slow; pass an all-in-place stack to avoid it. @@ -374,6 +375,7 @@ def write_string( :param prepend_middleware: List of middleware to prepend to the default stack. Only applicable if `unparse_stack` is None. :param bibtex_format: Customized BibTeX format to use (optional). + Writing a library with at least ``LARGE_LIBRARY_WARNING_THRESHOLD`` blocks logs a warning if the unparse stack deep-copies blocks (middlewares with ``allow_inplace_modification=False``), as that is slow; pass an all-in-place stack to avoid it. diff --git a/bibtexparser/middlewares/__init__.py b/bibtexparser/middlewares/__init__.py index 7202200d..4f5cee21 100644 --- a/bibtexparser/middlewares/__init__.py +++ b/bibtexparser/middlewares/__init__.py @@ -21,3 +21,31 @@ from .parsestack import default_parse_stack from .parsestack import default_unparse_stack + +# Declared explicitly so that sphinx autodoc documents these re-exports; +# without __all__, `automodule:: bibtexparser.middlewares` skips them all +# as imported members. +__all__ = [ + "AddEnclosingMiddleware", + "BlockMiddleware", + "LatexDecodingMiddleware", + "LatexEncodingMiddleware", + "LibraryMiddleware", + "MergeCoAuthors", + "MergeNameParts", + "MonthAbbreviationMiddleware", + "MonthIntMiddleware", + "MonthLongStringMiddleware", + "NameParts", + "NormalizeFieldKeys", + "RemoveEnclosingMiddleware", + "ResolveStringReferencesMiddleware", + "SeparateCoAuthors", + "SortBlocksByTypeAndKeyMiddleware", + "SortBlocksMiddleware", + "SortFieldsAlphabeticallyMiddleware", + "SortFieldsCustomMiddleware", + "SplitNameParts", + "default_parse_stack", + "default_unparse_stack", +]