[Docs] Implement mkdocstring to automatically create pydantic docsstrings

[maxschulz-COL]

Closes https://github.com/McK-Internal/vizro-internal/issues/1345

Description

PR is now based on a custom jinja template, essentially overwriting a fair bit of what the griffe-pydantic extension does/should do.

For lack of time, most of this was originally LLM created, but the results look stable and good.

New in the PR

• custom template for table for fields, similar to normal docstring parameters
• switching of docstring parameter style to table, which is (in my eyes) a lot clearer

Some quirks:

• had to write custom code to remove fields from TOC on the right hand side
• had to write custom code to detect default_factory and the default of fields that have been excluded from the schema

For review

Mainly check the API docs reference - models and actions have changed the most.

Not soved

I could not get the table to highlight on hover for the pydantic fields, unlike the normal table for docstring parameters

Screenshot

Notice

• I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":

  • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
  • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
  • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
  • I have not referenced individuals, products or companies in any commits, directly or indirectly.
  • I have not added data or restricted code in any commits, directly or indirectly.

[antonymilne]

Just a quick comment: "If fields do not have a description, they do not appear in attributes (maybe ok), and so they don't appear in TOC on the right" - this sounds good to me actually, since it prevents type from appearing presumably? I think it's fair enough to say that a field without a description shouldn't go in docs.

[maxschulz-COL]

Just a quick comment: "If fields do not have a description, they do not appear in attributes (maybe ok), and so they don't appear in TOC on the right" - this sounds good to me actually, since it prevents type from appearing presumably? I think it's fair enough to say that a field without a description shouldn't go in docs.

Hm maybe... I just don't like the mismatch with the TOC on the right hand side. If you scan that you could think that this attribute just doesn't exist. But I guess that's just taste.

The type I got rid of completely with the the extension

[Copilot]

Pull request overview

This PR implements mkdocstrings to automatically generate Pydantic docstrings from model field definitions, removing the need for manual Args: sections in docstrings. The changes clean up documentation by removing redundant "Defaults to X" text from field descriptions and add support for better automatic API documentation generation.

Changes:

• Implemented griffe-pydantic extension and FilterPrivateAttrs custom extension for automatic Pydantic docstring generation
• Removed manual Args: sections from model docstrings across all model files
• Removed "Defaults to X" text from field descriptions to avoid redundancy with auto-generated documentation
• Added constants API documentation page

Reviewed changes

Copilot reviewed 38 out of 39 changed files in this pull request and generated 21 comments.

Show a summary per file

File	Description
mkdocs.yml	Added griffe-pydantic plugin configuration and new constants documentation page
griffe_extensions.py	Added FilterPrivateAttrs extension to filter private attributes from generated docs
hatch.toml	Added griffe-pydantic dependency
constants.md	New documentation page for constants
Multiple model files	Removed Args sections, updated field descriptions, commented out validators
0.1.51.dev0.json	Updated schema to reflect docstring changes
changelog.d/*.md	Empty changelog fragment
.gitignore	Added .playwright-mcp/ entry

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[antonymilne]

This is super exciting 😁 Just skimmed through and left a couple of random comments and will review properly tomorrow!

[github-actions]

View the example dashboards of the current commit live on PyCafe ☕ 🚀

Updated on: 2026-01-28 10:59:21 UTC
Commit: 0578db8

Compare the examples using the commit's wheel file vs the latest released version:

vizro-core/examples/scratch_dev

View with commit's wheel vs View with latest release

vizro-core/examples/dev/

View with commit's wheel vs View with latest release

vizro-core/examples/visual-vocabulary/

View with commit's wheel vs View with latest release

vizro-core/examples/tutorial/

View with commit's wheel vs View with latest release