Repository navigation
Use Sphinx's mocking for dependencies in the docs build - #616
Merged
Merged
Conversation
The hand-written MagicMock modules made type annotations render as their repr, so Record.to_dataframe() was shown as returning <MagicMock id='...'>. autodoc_mock_imports shows the mocked name (pandas.DataFrame) instead. The rest of the generated HTML is unchanged.
tompollard
force-pushed
the
fix/docs-mock-annotation
branch
from
October 31, 2026 19:38
7715b82 to
b8c7eec
Compare
tompollard
added a commit
that referenced
this pull request
Nov 1, 2026
As discussed in #606: each change now adds its own file in `changelog.d/` instead of editing `docs/changes.rst`, so pull requests no longer conflict on the changelog. - Fragments are plain `.rst` files named after the change (for example `rr2ann-fixes.rst`), in the same bold-heading format as now. `changelog.d/README.rst` explains this. - At release time, `uv run towncrier build --version X.Y.Z --date "Mon YYYY"` adds a `Version X.Y.Z (Mon YYYY)` section to `docs/changes.rst` and deletes the fragments. Entries are sorted by file name. - The 25 existing unreleased entries are moved into `changelog.d/` unchanged. I checked that `towncrier build --draft` reproduces them exactly, and ran a real build on a copy: the docs build passes with `-W` both before and after. - `towncrier` is pinned in the `dev` group, like Ruff. AGENTS.md and DEVELOPING.md are updated. One trade-off: the unreleased changes no longer show on the docs site until a release. If you'd like them there, `sphinxcontrib-towncrier` can render a draft section, but that touches `docs/conf.py`, so I'd do it after #616. #619 and #583 add entries to `docs/changes.rst`, so they'd need to move them into a fragment after this is merged (or the other way round, whichever goes in first).
lukepayyapilli
approved these changes
Nov 4, 2026
lukepayyapilli
left a comment
lukepayyapilli
left a comment
Contributor
There was a problem hiding this comment.
Thanks Tom, checked b8c7eec9 locally merged with main:
- Docs build:
make -C docs html SPHINXOPTS="-W --keep-going"with--only-group docspasses on bothmainand the merged tree, with no warnings. - Output: comparing the generated HTML with
main, onlyio.htmlandwfdb.htmlchange, each in theto_dataframesignature (<MagicMock id='...'>becomespandas.DataFrame). The only other change is thatsearchindex.jsdrops themagicmockandidterms, so searching for them no longer finds the old signature. NoMagicMockrepr is left anywhere in the build.
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 API docs show
Record.to_dataframe()as returning<MagicMock id='...'>, becausedocs/conf.pyreplaced NumPy, pandas, SciPy and Matplotlib with hand-writtenMagicMockmodules, and the-> pd.DataFrameannotation rendered as the mock's repr.This switches to Sphinx's built-in
autodoc_mock_imports, which shows mocked names properly, so the signature now readsto_dataframe() → pandas.DataFrame.I compared the generated HTML with
main(numpydoc 1.7.0 and 1.11.0): apart from that signature inio.htmlandwfdb.html, every page is identical. The docs build passes with-W.