feat: Implement extension

Author: pawamoy

mkdocs.yml

@@ -74,7 +74,19 @@ plugins:
     nav_file: SUMMARY.txt
 - coverage
 - section-index
-- mkdocstrings
+- mkdocstrings:
+    handlers:
+      python:
+        import:
+        - https://docs.python.org/3/objects.inv
+        - https://mkdocstrings.github.io/griffe/objects.inv
+        options:
+          separate_signature: true
+          merge_init_into_class: true
+          docstring_options:
+            ignore_init_summary: true
+          extensions:
+          - griffe_typingdoc
 
 extra:
   social:

src/griffe_typingdoc/__init__.py

@@ -4,6 +4,8 @@
 Griffe extension for @tiangolo's `typing.doc` PEP.
 """
 
-from typing import List
+from __future__ import annotations
 
-__all__: List[str] = []  # noqa: WPS410 (the only __variable__ we use)
+from griffe_typingdoc.extension import TypingDocExtension as Extension
+
+__all__: list[str] = ["Extension"]  # noqa: WPS410

src/griffe_typingdoc/extension.py

@@ -0,0 +1,74 @@
+"""This module defines the Griffe TypingDoc extension."""
+
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+from typing import Annotated, Any
+
+from griffe.agents.extensions import VisitorExtension, When
+from griffe.agents.nodes import safe_get_annotation
+from griffe.dataclasses import Function
+from griffe.docstrings.dataclasses import DocstringParameter, DocstringSectionParameters
+
+from griffe_typingdoc.typing_doc import __typing_doc__
+
+
+@__typing_doc__(description="Griffe extension parsing the `typing.doc` decorator.")
+class TypingDocExtension(VisitorExtension):
+    """Griffe extension parsing the `typing.doc` decorator."""
+
+    when = When.after_all
+
+    @__typing_doc__(description="Visit a function definition.")
+    def visit_functiondef(
+        self,
+        node: Annotated[
+            ast.FunctionDef,
+            __typing_doc__(
+                description="The AST node describing the function definition.",
+            ),
+        ],
+    ) -> None:
+        """Visit a function definition.
+
+        This function takes a function definition node and visits its contents,
+        particularly its decorators, to build up the documentation metadata.
+        """
+        function: Function = self.visitor.current.members[node.name]  # type: ignore[assignment]
+
+        func_doc = {}
+        for decorator_node in node.decorator_list:
+            if isinstance(decorator_node, ast.Call):
+                if decorator_node.func.id == "__typing_doc__":  # type: ignore[attr-defined]
+                    func_doc.update({kw.arg: kw.value.value for kw in decorator_node.keywords})  # type: ignore[attr-defined]
+
+        params_doc: dict[str, dict[str, Any]] = defaultdict(dict)
+        for arg in node.args.args:
+            if isinstance(arg.annotation, ast.Subscript):
+                if arg.annotation.value.id == "Annotated":  # type: ignore[attr-defined]
+                    param_name = arg.arg
+                    params_doc[param_name]["annotation"] = safe_get_annotation(
+                        arg.annotation.slice.elts[0],  # type: ignore[attr-defined]
+                        function.parent,  # type: ignore[arg-type]
+                    )
+                    doc = arg.annotation.slice.elts[1]  # type: ignore[attr-defined]
+                    if isinstance(doc, ast.Call):
+                        if doc.func.id == "__typing_doc__":  # type: ignore[attr-defined]
+                            params_doc[param_name].update({kw.arg: kw.value.value for kw in doc.keywords})  # type: ignore[attr-defined,misc]
+
+        if func_doc or params_doc:
+            if function.docstring:
+                sections = function.docstring.parsed
+                if params_doc:
+                    docstring_params = []
+                    for param_name, param_doc in params_doc.items():  # noqa: WPS440
+                        docstring_params.append(
+                            DocstringParameter(
+                                name=param_name,
+                                description=param_doc["description"],
+                                annotation=param_doc["annotation"],
+                                value=function.parameters[param_name].default,
+                            ),
+                        )
+                    sections.append(DocstringSectionParameters(docstring_params))

src/griffe_typingdoc/typing_doc.py

@@ -0,0 +1,21 @@
+"""This module defines an alternate form of the `typing.doc` function.
+
+See https://github.com/tiangolo/fastapi/blob/typing-doc/typing_doc.md#alternate-form.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Type, TypeVar
+
+_Type = TypeVar("_Type")
+
+
+def __typing_doc__(  # noqa: N807
+    *,
+    description: str | None = None,
+    deprecated: bool = False,
+    discouraged: bool = False,
+    raises: Mapping[Type[BaseException], str | None] | None = None,
+    extra: dict[Any, Any] | None = None,
+) -> Callable[[_Type], _Type]:
+    return lambda _: _

tests/test_extension.py

@@ -0,0 +1,16 @@
+"""Tests for the Griffe extension."""
+
+from griffe.agents.extensions import Extensions
+from griffe.loader import GriffeLoader
+from griffe.docstrings.dataclasses import DocstringSectionKind
+
+from griffe_typingdoc.extension import TypingDocExtension
+
+
+def test_extension():
+    """Load our own package using the extension, assert a parameters section is added to the parsed docstring."""
+    loader = GriffeLoader(extensions=Extensions(TypingDocExtension()))
+    typingdoc = loader.load_module("griffe_typingdoc")
+    sections = typingdoc["extension.TypingDocExtension.visit_functiondef"].docstring.parsed
+    assert len(sections) == 2
+    assert sections[1].kind is DocstringSectionKind.parameters