Cross-link Matplotlib types in API docstring Returns blocks (#901)#903
Draft
drbenvincent wants to merge 1 commit into
Draft
Cross-link Matplotlib types in API docstring Returns blocks (#901)#903drbenvincent wants to merge 1 commit into
Returns blocks (#901)#903drbenvincent wants to merge 1 commit into
Conversation
Enable `napoleon_preprocess_types` and define `napoleon_type_aliases` so that type strings in NumPy-style `Parameters` and `Returns` blocks (e.g. `matplotlib.figure.Figure`, `xarray.DataArray`, `arviz.InferenceData`) become clickable cross-references resolved via intersphinx, instead of rendering as plain text. Also remove the dead `numpydoc_xref_*` configuration block, which had been silently ignored because the `numpydoc` Sphinx extension is not loaded — only `sphinx.ext.napoleon` parses docstrings here. Misleading comment header is replaced with explicit "Napoleon" / "sphinx-autodoc-typehints" section markers so future contributors can tell which extension owns which keys. Net effect on `make html`: 1047 -> 957 warnings (-90). The headline example from the issue (`InterruptedTimeSeries.plot` Returns block) now links `matplotlib.figure.Figure` to the upstream Matplotlib documentation. Co-authored-by: Cursor <cursoragent@cursor.com>
github-actions
Bot
added
the
documentation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #903 +/- ##
==========================================
- Coverage 94.74% 94.73% -0.02%
==========================================
Files 84 84
Lines 13131 13131
Branches 793 793
==========================================
- Hits 12441 12439 -2
- Misses 487 488 +1
- Partials 203 204 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
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.
Closes #901.
Summary
napoleon_preprocess_typesand define anapoleon_type_aliasesmap covering matplotlib (Figure,Axes), numpy (ndarray), pandas (DataFrame,Series,Index,Timestamp), xarray (DataArray,Dataset), arviz (InferenceData), pymc (Model), and pytensor (TensorVariable,RandomVariable). Both fully-qualified and short /np./pd./az./pm.-prefixed forms are aliased so existing docstrings work as-written.numpydoc_xref_*block fromdocs/source/conf.py. Those keys belong to thenumpydocSphinx extension, which is not in theextensionslist — onlysphinx.ext.napoleonis loaded — so the entire block was a silent no-op and was actively misleading.Napoleonandsphinx-autodoc-typehintssection markers so future contributors can see at a glance which extension owns which config keys.Verification
sphinx-build -b html -n docs/source docs/_buildwarning count drops from 1047 -> 957 (-90) on this branch.InterruptedTimeSeries.plot) now renders theReturnsblock'sfigentry as a clickable link to upstreammatplotlib.figure.Figure(confirmed against the rendered HTML).Return typeline emitted bysphinx-autodoc-typehintscontinues to render correctly — no regressions in that path.prek run(on the changed file) passes.Trade-off and follow-ups (deferred to land after #902)
Enabling Napoleon's type preprocessor reduces total warnings substantially, but introduces ~40 new ones in two specific shapes that this PR intentionally does not fix:
tuple[plt.Figure, list[plt.Axes]],dict[str, Any],tuple[pd.Series, pd.Series], andlist[matplotlib.axes.Axes]get split on the inner comma, producing broken:class:lookups. Affected primarily incausalpy/experiments/inverse_propensity_weighting.py,causalpy/experiments/panel_regression.py, and theReturnsblocks of every experiment'splot()method.EffectSummary,BaseExperiment,CheckResult,PipelineContextappear as bare class names in docstrings; Napoleon now tries to cross-reference them and (correctly) reports them as unresolved.These should be cleaned up in a follow-up PR sequenced after #902 lands, because:
causalpy/experiments/*(:param:blocks -> NumPy-styleParameterssections, plusRT03/PR04enforcement). Doing the type-string rewrites now would conflict with Widen numpydoc-validation checks across causalpy #902's docstring touches.Concretely, the follow-up PR should:
tuple of (Figure, list of Axes), etc.) or replace them with explicit:class:role markup at the call sites where the rewrite would hurt readability.EffectSummary,BaseExperiment,CheckResult,PipelineContext) so they cross-reference back into the local API docs.I'll open a follow-up issue capturing the above once this PR is in.
Independence from #902
This PR is config-only (
docs/source/conf.py); #902 ispyproject.toml+ docstrings. Zero file overlap, no merge order constraint either direction. They are net-additive: #902's docstring normalization makes #901's preprocessor more useful; #901's preprocessor makes #902's normalized types render as cross-references.Made with Cursor