[Docs] Implement mkdocstring to automatically create pydantic docsstrings

.gitignore

@@ -68,6 +68,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+.playwright-mcp/
 
 # Translations
 *.mo

vizro-core/changelog.d/20260120_184040_maximilian_schulz_mkdocstring_2.md

@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->

vizro-core/docs/griffe_extensions.py

@@ -3,6 +3,7 @@
 import griffe
 
 logger = griffe.get_logger("griffe_dynamically_inspect")
+filter_logger = griffe.get_logger("griffe_filter_private_attrs")
 
 
 class DynamicallyInspect(griffe.Extension):
@@ -33,3 +34,48 @@ def on_instance(self, *, obj: griffe.Object, **kwargs):  # noqa: D102
         logger.info("Dynamically inspecting '%s'", obj.path)
         inspected_module = griffe.inspect(obj.module.path, filepath=obj.filepath)
         obj.parent.set_member(obj.name, inspected_module[obj.name])
+
+
+class FilterPrivateAttrs(griffe.Extension):
+    """An extension to filter out private members from Pydantic model documentation.
+
+    This filters out:
+    - Attributes defined with PrivateAttr()
+    - The 'type' discriminator field
+    - Any methods/validators starting with underscore (e.g. _make_actions_chain)
+    """
+
+    def __init__(self, **kwargs):
+        """Accept kwargs for griffe compatibility."""
+
+    def _filter_private_attrs(self, cls: griffe.Class) -> None:
+        """Filter out private members from a Pydantic model class."""
+        try:
+            from pydantic import BaseModel
+
+            python_obj = griffe.dynamic_import(cls.path)
+            if python_obj is None or not issubclass(python_obj, BaseModel):
+                return
+
+            private_attrs = getattr(python_obj, "__private_attributes__", {})
+            for name in list(cls.members.keys()):
+                if name in private_attrs:
+                    cls.del_member(name)
+                    filter_logger.info(f"Filtered out PrivateAttr '{name}' from {cls.path}")
+                elif name == "type":
+                    cls.del_member(name)
+                    filter_logger.info(f"Filtered out 'type' field from {cls.path}")
+                elif name.startswith("_") and not name.startswith("__"):
+                    cls.del_member(name)
+                    filter_logger.info(f"Filtered out private member '{name}' from {cls.path}")
+        except (ImportError, AttributeError, TypeError):
+            pass
+
+    def on_class_members(self, *, cls: griffe.Class, **kwargs):
+        """Filter out PrivateAttr members when class members are collected."""
+        self._filter_private_attrs(cls)
+
+    def on_instance(self, *, obj: griffe.Object, **kwargs):
+        """Filter out PrivateAttr members after all processing is complete."""
+        if isinstance(obj, griffe.Class):
+            self._filter_private_attrs(obj)

vizro-core/docs/pages/API-reference/constants.md

@@ -0,0 +1,11 @@
+# Constants
+
+Constants used in Vizro.
+
+<!-- vale off -->
+
+::: vizro._constants.GAP_DEFAULT
+
+::: vizro.models._grid.MIN_DEFAULT
+
+<!-- vale on -->

vizro-core/hatch.toml

@@ -125,6 +125,7 @@ dependencies = [
   "linkchecker",
   "mkdocs-open-in-new-tab",
   "mkdocs-pycafe",
+  "griffe-pydantic",
   "PyGithub",
   "playwright"
 ]

vizro-core/mkdocs.yml

@@ -57,6 +57,7 @@ nav:
       - Table functions: pages/API-reference/table-callables.md
       - Figure functions: pages/API-reference/figure-callables.md
       - Kedro integration: pages/API-reference/kedro-integration.md
+      - Constants: pages/API-reference/constants.md
       - Deprecations: pages/API-reference/deprecations.md
   - Find out more:
       - Technical:
@@ -219,7 +220,12 @@ plugins:
             merge_init_into_class: true
             docstring_section_style: list
             separate_signature: true
-            #   filters: ["!^_"]
+            unwrap_annotated: true # check effect
+            show_symbol_type_heading: true
+            show_symbol_type_toc: false
+            signature_crossrefs: true
+            show_signature_annotations: true
+            filters: ["!^_"] # Hide private attributes (names starting with underscore)
             show_root_heading: true
             docstring_options:
               ignore_init_summary: true
@@ -232,7 +238,13 @@ plugins:
               - griffe_warnings_deprecated:
                   kind: danger
                   title: Deprecated
+              - griffe_pydantic:
+                  schema: true
+              - docs/griffe_extensions.py:FilterPrivateAttrs
           paths: [src]
+          inventories:
+            - https://docs.python.org/3/objects.inv
+            - https://docs.pydantic.dev/latest/objects.inv
   - git-revision-date-localized:
       enable_creation_date: false
 extra_css: