docs: consolidate pydantic Field descriptions with numpydoc Parameters (#1700)#2572
Open
anevolbap wants to merge 10 commits into
Open
docs: consolidate pydantic Field descriptions with numpydoc Parameters (#1700)#2572anevolbap wants to merge 10 commits into
anevolbap wants to merge 10 commits into
Conversation
Wire sphinxcontrib.autodoc_pydantic in conf.py with conservative defaults (hide JSON schema, validator, and Config summaries; show field defaults and constraints). With descriptions now sourced from Field(description=...) on pydantic models, drop the duplicated numpydoc Parameters block on HSGPKwargs. Refs pymc-labs#1700.
Drop the numpydoc Parameters blocks on VariableScaling, DataDerivedScaling, FixedScaling, and Scaling. Field(description=...) is now the single source and is rendered by autodoc-pydantic. Expand the value description on FixedScaling and the dims description on VariableScaling to retain the detail that was only in the docstring. Refs pymc-labs#1700.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2572 +/- ##
=======================================
Coverage 93.90% 93.90%
=======================================
Files 92 92
Lines 14078 14078
=======================================
Hits 13220 13220
Misses 858 858 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
…description Restore the **emphasis** and × character that were in the original numpydoc text for FixedScaling.value. Also move autodoc-pydantic next to numpydoc in pyproject.toml docs extras since they are companion rendering tools.
anevolbap
changed the title
The autodoc-pydantic extension did not reliably render Field descriptions through the autosummary template on ReadTheDocs. Replace it with a small autodoc-process-docstring callback that emits :param: and :type: directives for the 5 pydantic classes this PR touches, sourced from Field(description=...). Drops the autodoc-pydantic dep.
| return str(annotation).replace("typing.", "") | ||
|
|
||
|
|
||
| _PYDANTIC_PARAMETERS_INJECT_TARGETS = frozenset( |
|
|
||
| Parameters | ||
| ---------- | ||
| m : int |
Contributor
There was a problem hiding this comment.
Some of the rendering here:
https://pymc-marketing--2572.org.readthedocs.build/en/2572/api/generated/pymc_marketing.hsgp_kwargs.HSGPKwargs.html
is not amazing (missing periods / no line breaks, etc)
Drop the bespoke autodoc-process-docstring callback in favor of sphinxcontrib.autodoc_pydantic, the canonical Sphinx extension for this. Sphinx 9.x's autosummary picks templates via hard-coded heuristics that do not respect autodoc-pydantic's documenter priority, so generated stubs use autoclass; a small source-read hook swaps autoclass for autopydantic_model for any BaseModel subclass and pulls inherited fields with :inherited-members: BaseModel. Restructure HSGPKwargs.L so the description lives on the outer Field (instead of nested inside Annotated, where autodoc-pydantic cannot read it), and end field descriptions with periods.
Unescaped asterisks in two Field descriptions were interpreted as inline-emphasis start markers; the warning only surfaces once autopydantic_model documents these fields inline (autosummary stubs swallow it). Wrap in double backticks to typeset as code.
… models The autosummary class template was listing pydantic v1 legacy methods (construct, copy, dict, from_orm, json, parse_*, schema_*, validate, update_forward_refs, model_parametrized_name) in the Methods table and duplicating user fields plus pydantic v2 internals (model_config, model_fields, ...) in the Attributes table. With autopydantic_model now documenting fields inline, drop the Attributes block for pydantic classes and exclude the v1 aliases from Methods.
This was referenced May 16, 2026
Contributor
Author
|
Drafted a smaller alternative as #2577 (option A from the issue: drops |
Collaborator
|
@anevolbap do you wanna resolve the conflicts ? |
Contributor
Author
@juanitorduz, this PR was option B of two alternatives I drafted for #1700 (option A was #2577). #2577 is already merged and closed the issue, so the conflicts here are not worth resolving as-is. Happy to rebase and switch the repo over to this approach its rendering reads better than the plain numpydoc one that landed (imo, it does not). Otherwise this can be closed. |
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
3 participants
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 #1700.
Makes
Field(description=...)the single source of truth for field documentation on the pydantic models that previously duplicated descriptions in a numpydocParametersblock. A smallautodoc-process-docstringcallback inconf.pyemits:param:/:type:directives frommodel_fields, so descriptions render in the published docs without an extra extension.Touches 5 classes:
HSGPKwargsinpymc_marketing/hsgp_kwargs.pyVariableScaling,DataDerivedScaling,FixedScaling,Scalinginpymc_marketing/mmm/scaling.pyField descriptions are expanded where the docstring carried detail the Field text didn't (
cov_func,dims,FixedScaling.value). The other pydantic models in the repo are out of scope: they either have noParametersblock to consolidate or have hand-written docstrings the injector would clash with.RTD preview: https://pymc-marketing--2572.org.readthedocs.build/en/2572/api/generated/pymc_marketing.hsgp_kwargs.HSGPKwargs.html