feat: Support more experimental annotations (names, deprecations, warnings, exceptions)

Issue #1: #1
PR #3: #3

Author: pawamoy

docs/examples.md

@@ -0,0 +1,29 @@
+# Examples
+
+## Simple
+
+/// details | `simple` Python module
+    type: example
+
+```python
+--8<-- "docs/examples/simple.py"
+```
+///
+
+::: simple
+    options:
+        heading_level: 3
+
+## Enhanced
+
+/// details | `enhanced` Python module
+    type: example
+
+```python
+--8<-- "docs/examples/enhanced.py"
+```
+///
+
+::: enhanced
+    options:
+        heading_level: 3

docs/examples/enhanced.py

@@ -0,0 +1,93 @@
+# This gist shows how we could get rid of docstrings micro-syntax
+# like Google-style and Numpydoc-style pseudo-standards,
+# using an enhanced version of PEP 727.
+
+# The goal is to replace the following sections:
+
+# Deprecated
+# Parameters
+# Other Parameters
+# Raises
+# Warns
+# Yields
+# Receives
+# Returns
+
+from __future__ import annotations
+
+from typing import (
+    Annotated,
+    Generator,
+    Deprecated,
+    Doc,
+    Name,
+    Raises,
+    Warns,
+)
+
+
+# Documenting deprecations, replacing Deprecated sections:
+DEPRECATED: Annotated[
+    int,
+    Deprecated(
+        """Deprecated since v2.
+
+        Please stop using this deprecated attribute, thanks!
+        """
+    ),
+    Doc("Showing off deprecated attributes."),
+]
+
+
+# For functions, maybe add the information to the return value annotation:
+def deprecated1() -> Annotated[None, Deprecated("Deprecated since v2.")]:
+    """Showing off deprecated functions."""
+
+
+# For parameters:
+def deprecated2(param1: Annotated[int, Deprecated("Deprecated since v2."), Doc("Description of param1.")] = 0):
+    """Showing off deprecated parameters."""
+
+
+# Documenting exceptions, replacing Raises sections,
+# maybe add the information to the return value annotation:
+def exceptions() -> (
+    Annotated[
+        None,
+        Raises(ValueError, "When something goes wrong."),
+        Raises(TypeError, "When something goes even wronger."),
+    ]
+):
+    """Showing off raised exceptions."""
+
+
+# Documenting warnings, replacing Warns sections,
+# maybe add the information to the return value annotation:
+def warnings() -> (
+    Annotated[
+        None,
+        Warns(FutureWarning, "Hello users."),
+        Warns(DeprecationWarning, "Hello developers."),
+    ]
+):
+    """Showing off emitted warnings."""
+
+
+# Advanced use-case: documenting multiple yielded/received/returned values:
+def return_tuple() -> (
+    Generator[
+        tuple[
+            Annotated[int, Name("python"), Doc("First element of the yielded value.")],
+            Annotated[float, Name("cobra"), Doc("Second element of the yielded value.")],
+        ],
+        tuple[
+            Annotated[int, Name("beep"), Doc("First element of the received value.")],
+            Annotated[float, Name("boop"), Doc("Second element of the received value.")],
+        ],
+        tuple[
+            Annotated[int, Name("super"), Doc("First element of the returned value.")],
+            Annotated[float, Name("hyper"), Doc("Second element of the returned value.")],
+        ],
+    ]
+):
+    """Showing off tuples as yield/receive/return values."""

docs/examples/simple.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import (
+    Annotated,
+    Generator,
+    Iterator,
+    NotRequired,
+    TypedDict,
+    Unpack,
+    Doc,
+)
+
+# Documenting module/class attributes, replacing Attributes sections:
+ATTRIBUTE: Annotated[
+    str,
+    Doc(
+        """Showing off attributes.
+
+        Supporting multiple lines.
+        """
+    )
+]
+
+
+# Documenting parameters, replacing Parameters sections:
+def parameters(param1: Annotated[str, Doc("Description of param1.")] = "default"):
+    """Showing off parameters."""
+
+
+# Documenting other parameters (keyword arguments), replacing Other Parameters sections:
+class OtherParameters(TypedDict, total=False):
+    """Keyword arguments of [`simple.other_parameters`][]."""
+    param1: Annotated[NotRequired[str], Doc("Description of param1.")]
+    param2: Annotated[NotRequired[str], Doc("Description of param2.")]
+
+
+def other_parameters(
+    **kwargs: Annotated[Unpack[OtherParameters], Doc("See other parameters.")],  # noqa: ARG001
+) -> None:
+    """Showing off other parameters."""
+
+
+# Documenting yielded and received values, replacing Yields and Receives sections:
+def generator() -> (
+    Generator[
+        Annotated[int, Doc("Yielded integers.")],
+        Annotated[int, Doc("Received integers.")],
+        Annotated[int, Doc("Final returned value.")],
+    ]
+):
+    """Showing off generators."""
+
+
+# Same thing with Iterator instead of Generator:
+def iterator() -> Iterator[Annotated[int, Doc("Yielded integers.")]]:
+    """Showing off iterators."""
+
+
+# Advanced use-case: documenting multiple yielded/received/returned values:
+def return_tuple() -> (
+    Generator[
+        tuple[
+            Annotated[int, Doc("First element of the yielded value.")],
+            Annotated[float, Doc("Second element of the yielded value.")],
+        ],
+        tuple[
+            Annotated[int, Doc("First element of the received value.")],
+            Annotated[float, Doc("Second element of the received value.")],
+        ],
+        tuple[
+            Annotated[int, Doc("First element of the returned value.")],
+            Annotated[float, Doc("Second element of the returned value.")],
+        ],
+    ]
+):
+    """Showing off tuples as yield/receive/return values."""

mkdocs.yml

@@ -19,6 +19,7 @@ nav:
   - Changelog: changelog.md
   - Credits: credits.md
   - License: license.md
+- Examples: examples.md
 # defer to gen-files + literate-nav
 - API reference:
   - Griffe TypingDoc: reference/
@@ -78,6 +79,7 @@ markdown_extensions:
 - admonition
 - callouts
 - footnotes
+- pymdownx.blocks.details
 - pymdownx.emoji:
     emoji_index: !!python/name:materialx.emoji.twemoji
     emoji_generator: !!python/name:materialx.emoji.to_svg
@@ -110,6 +112,7 @@ plugins:
         import:
         - https://docs.python.org/3/objects.inv
         - https://mkdocstrings.github.io/griffe/objects.inv
+        paths: [src, docs/examples]
         options:
           docstring_options:
             ignore_init_summary: true

src/griffe_typingdoc/__init__.py

@@ -5,6 +5,6 @@
 
 from __future__ import annotations
 
-from griffe_typingdoc.extension import TypingDocExtension as Extension
+from griffe_typingdoc._extension import TypingDocExtension
 
-__all__: list[str] = ["Extension"]
+__all__: list[str] = ["TypingDocExtension"]

src/griffe_typingdoc/_docstrings.py

@@ -0,0 +1,134 @@
+"""Helpers to build docstring sections."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterator
+
+from griffe.docstrings.dataclasses import (
+    DocstringParameter,
+    DocstringRaise,
+    DocstringReceive,
+    DocstringReturn,
+    DocstringSectionAdmonition,
+    DocstringSectionOtherParameters,
+    DocstringSectionParameters,
+    DocstringSectionRaises,
+    DocstringSectionReceives,
+    DocstringSectionReturns,
+    DocstringSectionWarns,
+    DocstringSectionYields,
+    DocstringWarn,
+    DocstringYield,
+)
+
+if TYPE_CHECKING:
+    from griffe import Function
+    from griffe.dataclasses import Parameter
+
+
+def _no_self_params(func: Function) -> list[Parameter]:
+    if func.parent and func.parent.is_class and func.parameters[0].name in {"self", "cls"}:
+        return list(func.parameters)[1:]
+    return list(func.parameters)
+
+
+def _to_parameters_section(params_dict: dict[str, dict[str, Any]], func: Function) -> DocstringSectionParameters:
+    return DocstringSectionParameters(
+        [
+            DocstringParameter(
+                name=param_name,
+                description=param_doc["description"],
+                annotation=param_doc["annotation"],
+                value=func.parameters[param_name].default,  # type: ignore[arg-type]
+            )
+            for param_name, param_doc in params_dict.items()
+        ],
+    )
+
+
+def _to_other_parameters_section(params_dict: dict[str, dict[str, Any]]) -> DocstringSectionOtherParameters:
+    return DocstringSectionOtherParameters(
+        [
+            DocstringParameter(
+                name=param_name,
+                description=param_doc["description"],
+                annotation=param_doc["annotation"],
+            )
+            for param_name, param_doc in params_dict.items()
+        ],
+    )
+
+
+def _to_yields_section(yield_data: Iterator[dict[str, Any]]) -> DocstringSectionYields:
+    return DocstringSectionYields(
+        [
+            DocstringYield(
+                name=yield_dict.get("name", ""),
+                description=yield_dict.get("doc", ""),
+                annotation=yield_dict["annotation"],
+            )
+            for yield_dict in yield_data
+        ],
+    )
+
+
+def _to_receives_section(receive_data: Iterator[dict[str, Any]]) -> DocstringSectionReceives:
+    return DocstringSectionReceives(
+        [
+            DocstringReceive(
+                name=receive_dict.get("name", ""),
+                description=receive_dict.get("doc", ""),
+                annotation=receive_dict["annotation"],
+            )
+            for receive_dict in receive_data
+        ],
+    )
+
+
+def _to_returns_section(return_data: Iterator[dict[str, Any]]) -> DocstringSectionReturns:
+    return DocstringSectionReturns(
+        [
+            DocstringReturn(
+                name=return_dict.get("name", ""),
+                description=return_dict.get("doc", ""),
+                annotation=return_dict["annotation"],
+            )
+            for return_dict in return_data
+        ],
+    )
+
+
+def _to_warns_section(warn_data: Iterator[dict[str, Any]]) -> DocstringSectionWarns:
+    return DocstringSectionWarns(
+        [
+            DocstringWarn(
+                annotation=warn_dict["annotation"],
+                description=warn_dict.get("description", ""),
+            )
+            for warn_dict in warn_data
+        ],
+    )
+
+
+def _to_raises_section(raise_data: Iterator[dict[str, Any]]) -> DocstringSectionRaises:
+    return DocstringSectionRaises(
+        [
+            DocstringRaise(
+                annotation=raise_dict["annotation"],
+                description=raise_dict.get("description", ""),
+            )
+            for raise_dict in raise_data
+        ],
+    )
+
+
+def _to_deprecated_section(deprecation_data: dict[str, Any]) -> DocstringSectionAdmonition:
+    description = deprecation_data["description"]
+    description_lines = deprecation_data["description"].split("\n")
+    if len(description_lines) > 1:
+        title = description_lines[0].strip()
+        description = "\n".join(description_lines[1:]).strip()
+    else:
+        title = description
+        description = ""
+    return DocstringSectionAdmonition(kind="danger", title=title, text=description)