fixup! refactor: Use dataclasses for configuration/options and automate schema generation

Author: pawamoy

mkdocs.yml

@@ -163,6 +163,8 @@ plugins:
           docstring_options:
             ignore_init_summary: true
           docstring_section_style: list
+          extensions:
+          - scripts/griffe_extensions.py
           filters: ["!^_"]
           heading_level: 1
           inherited_members: true

pyproject.toml

@@ -33,6 +33,7 @@ dependencies = [
     "mkdocstrings>=0.28",
     "mkdocs-autorefs>=1.2",
     "griffe>=0.49",
+    "typing-extensions>=4.0; python_version < '3.11'",
 ]
 
 [project.urls]
@@ -106,6 +107,7 @@ dev = [
     "mkdocs-git-revision-date-localized-plugin>=1.2",
     "mkdocs-literate-nav>=0.6",
     "mkdocs-material>=9.5",
+    "pydantic>=2.10",
     "mkdocs-minify-plugin>=0.8",
     # YORE: EOL 3.10: Remove line.
     "tomli>=2.0; python_version < '3.11'",

scripts/griffe_extensions.py

@@ -0,0 +1,46 @@
+"""Custom extensions for Griffe."""
+
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+import griffe
+
+logger = griffe.get_logger("griffe_extensions")
+
+
+class CustomFields(griffe.Extension):
+    """Support our custom dataclass fields."""
+
+    def on_attribute_instance(
+        self,
+        *,
+        attr: griffe.Attribute,
+        agent: griffe.Visitor | griffe.Inspector,
+        **kwargs: Any,  # noqa: ARG002
+    ) -> None:
+        """Fetch descriptions from `Field` annotations."""
+        if attr.docstring:
+            return
+        try:
+            field: griffe.ExprCall = attr.annotation.slice.elements[1]  # type: ignore[union-attr]
+        except AttributeError:
+            return
+
+        if field.canonical_path == "mkdocstrings_handler.python.config.Field":
+            description = next(
+                attr.value
+                for attr in field.arguments
+                if isinstance(attr, griffe.ExprKeyword) and attr.name == "description"
+            )
+            if not isinstance(description, str):
+                logger.warning(f"Field description of {attr.path} is not a static string")
+                description = str(description)
+
+            attr.docstring = griffe.Docstring(
+                ast.literal_eval(description),
+                parent=attr,
+                parser=agent.docstring_parser,
+                parser_options=agent.docstring_options,
+            )

scripts/mkdocs_hooks.py

@@ -22,11 +22,11 @@
 def on_post_build(config: MkDocsConfig, **kwargs: Any) -> None:  # noqa: ARG001
     """Write `schema.json` to the site directory."""
     if TypeAdapter is None:
-        logger.info("pydantic is not installed, skipping JSON schema generation")
+        logger.info("Pydantic is not installed, skipping JSON schema generation")
         return
     adapter = TypeAdapter(PythonInputConfig)
     schema = adapter.json_schema()
     schema["$schema"] = "https://json-schema.org/draft-07/schema"
     with open(join(config.site_dir, "schema.json"), "w") as file:
         json.dump(schema, file, indent=2)
-        print(f"Dumped JSON schema {file}")
+        logger.debug("Generated JSON schema")