docs: Document built-in, official and third-party extensions

docs/extensions/built-in.md

@@ -0,0 +1,7 @@
+# Built-in extensions
+
+Built-in extensions are maintained in Griffe's code base. They generally bring support for core features of the Python language or its standard library.
+
+Available built-in extensions:
+
+- [`dataclasses`](built-in/dataclasses.md): Support for [`dataclasses`][].

docs/extensions/built-in/dataclasses.md

@@ -0,0 +1,5 @@
+# `dataclasses`
+
+The `dataclasses` extension adds support for [dataclasses][] from the standard library. It works both statically and dynamically. When used statically, it re-creates the `__init__` methods and their signatures (as Griffe objects), that would otherwise be created at runtime. When used dynamically, it does nothing since `__init__` methods are created by the library and can be inspected normally.
+
+**This extension is enabled by default.**

docs/extensions/official.md

@@ -0,0 +1,11 @@
+# Official extensions
+
+Official extensions are developed and maintained within the mkdocstrings organization on GitHub, in separated repositories. They generally bring support for various third-party libraries or other documentation-related features that are part of Python's standard library.
+
+Available official extensions:
+
+- [`inherited-docstrings`](official/inherited-docstrings.md): Inherit docstrings from parent classes.
+- [`pydantic`](official/pydantic.md): Support for [Pydantic](https://docs.pydantic.dev/latest/) models. [:octicons-heart-fill-24:{ .pulse } Sponsors only](../insiders/index.md){ .insiders }
+- [`sphinx`](official/sphinx.md): Parse [Sphinx](https://www.sphinx-doc.org/)-comments above attributes (`#:`) as docstrings. [:octicons-heart-fill-24:{ .pulse } Sponsors only](../insiders/index.md){ .insiders }
+- [`typing-doc`](official/typingdoc.md): Support for [PEP 727](https://peps.python.org/pep-0727/)'s [`typing.Doc`][typing_extensions.Doc], "Documentation in Annotated Metadata".
+- [`warnings-deprecated`](official/warnings-deprecated.md): Support for [PEP 702](https://peps.python.org/pep-0702/)'s [`warnings.deprecated`][], "Marking deprecations using the type system". [:octicons-heart-fill-24:{ .pulse } Sponsors only](../insiders/index.md){ .insiders }

docs/extensions/official/inherited-docstrings.md

@@ -0,0 +1,28 @@
+# `griffe-inherited-docstrings`
+
+- **PyPI**: [`griffe-inherited-docstrings`](https://pypi.org/project/griffe-inherited-docstrings/)
+- **GitHub**: [mkdocstrings/griffe-inherited-docstrings](https://github.com/mkdocstrings/griffe-inherited-docstrings)
+- **Documentation:** [mkdocstrings.github.io/griffe-inherited-docstrings](https://mkdocstrings.github.io/griffe-inherited-docstrings)
+- **Extension name:** `griffe_inherited_docstrings`
+
+---
+
+This extension, when enabled, iterates on the declared members of all classes found within a package, and if they don't have a docstring, but have a parent member with a docstring, sets their docstring to this parent docstring.
+
+```python
+class Base:
+    attr = "hello"
+    """Hello."""
+
+    def hello(self):
+        """Hello again."""
+        ...
+
+class Derived(Base):
+    attr = "bye"
+
+    def hello(self):
+        ...
+```
+
+Following with example, *without* the extension `Derived.attr` and `Derived.hello` have no docstrings, while *with* the extension they will have the `Base.attr` and `Base.hello` docstrings attached, respectively.

docs/extensions/official/pydantic.md

@@ -0,0 +1,12 @@
+# `griffe-pydantic`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders }
+
+- **PyPI**: [`griffe-pydantic`](https://pypi.org/project/griffe-pydantic/)
+- **GitHub**: [mkdocstrings/griffe-pydantic](https://github.com/mkdocstrings/griffe-pydantic)
+- **Documentation:** [mkdocstrings.github.io/griffe-pydantic](https://mkdocstrings.github.io/griffe-pydantic)
+- **Extension name:** `griffe_pydantic`
+
+---
+
+This extension adds support for [Pydantic](https://docs.pydantic.dev/latest/) models. It extracts useful information from them, stores this information into the `extra` attribute of objects, and binds custom mkdocstrings templates to the objects for better rendering. The extension works both statically and dynamically, and supports model inheritance.

docs/extensions/official/sphinx.md

@@ -0,0 +1,38 @@
+# `griffe-sphinx`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders }
+
+- **PyPI**: [`griffe-sphinx`](https://pypi.org/project/griffe-sphinx/)
+- **GitHub**: [mkdocstrings/griffe-sphinx](https://github.com/mkdocstrings/griffe-sphinx)
+- **Documentation:** [mkdocstrings.github.io/griffe-sphinx](https://mkdocstrings.github.io/griffe-sphinx)
+- **Extension name:** `griffe_sphinx`
+
+---
+
+This extension reads Sphinx-comments above attribute assignments to use them as docstrings.
+
+```python
+#: Summary of `module_attr`. 
+module_attr = "hello"
+
+
+class Hello:
+    #: Summary of `class_attr`.
+    #:
+    #: Description of the class attribute.
+    #: *Markup* and [cross-references][] are __supported__,
+    #: just like in regular docstrings.
+    class_attr = "hello"
+
+    def __init__(self):
+        #: Summary of `instance_attr`.
+        self.instance_attr = "hello"
+```
+
+Comments are treated exactly like regular docstrings: they are "cleaned" (dedented, stripped of leading and trailing new lines) and contain any markup you want, be it Markdown, rST, AsciiDoc, etc.
+
+Trailing comments are not supported:
+
+```python
+module_attr  #: This is not supported.
+```

docs/extensions/official/typingdoc.md

@@ -0,0 +1,43 @@
+# `griffe-typingdoc`
+
+- **PyPI**: [`griffe-typingdoc`](https://pypi.org/project/griffe-typingdoc/)
+- **GitHub**: [mkdocstrings/griffe-typingdoc](https://github.com/mkdocstrings/griffe-typingdoc)
+- **Documentation:** [mkdocstrings.github.io/griffe-typingdoc](https://mkdocstrings.github.io/griffe-typingdoc)
+- **Extension name:** `griffe_typingdoc`
+
+---
+
+This extension reads docstrings for parameters, return values and more from type annotation using [`Annotated`][typing.Annotated] and the [`Doc`][typing_extensions.Doc] class suggested in [PEP 727](https://peps.python.org/pep-0727/). Documenting parameters and return values this way makes it possible to completely avoid relying on a particular "docstring style" (Google, Numpydoc, Sphinx, etc.) and just use plain markup in module/classes/function docstrings. Docstrings therefore do not have to be parsed at all. 
+
+```python
+from typing import Annotated as An
+from typing_extensions import Doc
+
+
+def function(
+    param1: An[int, Doc("Some integer value.")],
+    param2: An[
+        str,
+        Doc(
+            """
+            Summary of the parameter.
+
+            Multi-line docstrings can be used, as usual.
+            Any **markup** is supported, as usual.
+            """
+        )
+    ]
+) -> An[bool, Doc("Whether you like PEP 727.")]:
+    """Summary of the function.
+
+    No more "Args", "Parameters" or "Returns" sections.
+    Just plain markup.
+    """
+    ...
+```
+
+PEP 727 is likely to be withdrawn or rejected, but the `Doc` class will remain in `typing_extensions`, [as told by Jelle Zijlstra](https://discuss.python.org/t/pep-727-documentation-metadata-in-typing/32566/183):
+
+> We’ll probably keep it in `typing_extensions` indefinitely even if the PEP gets withdrawn or rejected, for backwards compatibility reasons.
+>
+> You are free to use it in your own code using the typing-extensions version. If usage of `typing_extensions.Doc` becomes widespread, that will be a good argument for accepting the PEP and putting it in the standard library.

docs/extensions/official/warnings-deprecated.md

@@ -0,0 +1,24 @@
+# `griffe-warnings-deprecated`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders }
+
+- **PyPI**: [`griffe-warnings-deprecated`](https://pypi.org/project/griffe-warnings-deprecated/)
+- **GitHub**: [mkdocstrings/griffe-warnings-deprecated](https://github.com/mkdocstrings/griffe-warnings-deprecated)
+- **Documentation:** [mkdocstrings.github.io/griffe-warnings-deprecated](https://mkdocstrings.github.io/griffe-warnings-deprecated)
+- **Extension name:** `griffe_warnings_deprecated`
+
+---
+
+This extension adds support for functions and classes decorated with [`@warnings.deprecated(...)`][warnings.deprecated], as implemented thanks to [PEP 702](https://peps.python.org/pep-0702/). The message provided in the decorator call will be stored in the corresponding Griffe object's [`deprecated`][griffe.Object.deprecated] attribute (usable by downstream rendering templates), and will also add an admonition to the object's docstring with the provided message as text.
+
+```python
+from warnings import deprecated
+
+@deprecated("This function is **deprecated**. Use [another one][package.another_func] instead.")
+def deprecated_func():
+    ...
+
+
+def another_func():
+    ...
+```

docs/extensions/third-party.md

@@ -0,0 +1,13 @@
+# Third-party extensions
+
+Third-party extensions are developed and maintained outside of the mkdocstrings organization, by various developers. They generally bring support for third-party libraries.
+
+Available third-party extensions:
+
+- [`docstring-inheritance`](third-party/docstring-inheritance.md): A more advanced docstring inheritance utility that also provides a Griffe extension.
+- [`fieldz`](third-party/fieldz.md): Support for data-class like objects (dataclasses, pydantic, attrs, etc.) using [fieldz](https://github.com/pyapp-kit/fieldz).
+- [`generics`](third-party/generics.md): Resolve generic type parameters as bound types in subclasses.
+- [`inherited-method-crossrefs`](third-party/inherited-method-crossrefs.md): Replace docstrings of inherited methods with cross-references to parents.
+- [`modernized-annotations`](third-party/modernized-annotations.md): Modernize type annotations by adopting PEP 585 and PEP 604.
+
+You can find more third-party extensions by exploring the [`griffe-extension` topic on GitHub](https://github.com/topics/griffe-extension). You can also check out the "in-project" extensions (not published to PyPI) used in various projects on GitHub by [searching for "griffe extension" in code](https://github.com/search?q=griffe+Extension+language%3Apython&type=code).

docs/extensions/third-party/docstring-inheritance.md

@@ -0,0 +1,20 @@
+# `docstring-inheritance`
+
+- **PyPI**: [`docstring-inheritance`](https://pypi.org/project/docstring-inheritance/)
+- **GitHub**: [AntoineD/docstring-inheritance](https://github.com/AntoineD/docstring-inheritance)
+- **Extension name:** `docstring_inheritance.griffe`
+
+---
+
+`docstring-inheritance` is a Python package that allows to avoid writing and maintaining duplicated Python docstrings. The typical usage is to enable the inheritance of the docstrings from a base class such that its derived classes fully or partially inherit the docstrings. It provides a Griffe extension and recommends to use it alongside the official [`inherited-docstrings`](../official/inherited-docstrings.md) extension in MkDocs:
+
+```yaml
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          extensions:
+          - griffe_inherited_docstrings
+          - docstring_inheritance.griffe
+```

docs/extensions/third-party/fieldz.md

@@ -0,0 +1,16 @@
+# `griffe-fieldz`
+
+- **PyPI**: [`griffe-fieldz`](https://pypi.org/project/griffe-fieldz/)
+- **GitHub**: [pyapp-kit/griffe-fieldz](https://github.com/pyapp-kit/griffe-fieldz)
+- **Extension name:** `griffe_fieldz`
+
+---
+
+This extension adds support for data-class like things (pydantic, attrs, etc...). This extension will inject the fields of the data-class into the documentation, preventing you from duplicating field metadata in your docstrings.
+
+It supports anything that [fieldz](https://github.com/pyapp-kit/fieldz) supports, which is currently:
+
+- [`dataclasses.dataclass`](https://docs.python.org/3/library/dataclasses.html#dataclasses.dataclass)
+- [`pydantic.BaseModel`](https://docs.pydantic.dev/latest/)
+- [`attrs.define`](https://www.attrs.org/en/stable/overview.html)
+- [`msgspec.Struct`](https://jcristharif.com/msgspec/)

docs/extensions/third-party/generics.md

@@ -0,0 +1,9 @@
+# `griffe-generics`
+
+- **PyPI**: [`griffe-generics`](https://pypi.org/project/griffe-generics/)
+- **GitHub**: [jonghwanhyeon/griffe-generics](https://github.com/jonghwanhyeon/griffe-generics)
+- **Extension name:** `griffe_generics`
+
+---
+
+This extension resolves generic type parameters as bound types in subclasses. For example, if a parent class inherits from `Generics[L]`, and a subclass specifies `L` as `Hashable`, then all type annotations using `L` in the class methods or attributes inherited from the parent class will be transformed to use `Hashable` instead.

docs/extensions/third-party/inherited-method-crossrefs.md

@@ -0,0 +1,15 @@
+# `griffe-inherited-method-crossrefs`
+
+- **PyPI**: [`griffe-inherited-method-crossrefs`](https://pypi.org/project/griffe-inherited-method-crossrefs/)
+- **GitHub**: [mlprt/griffe-inherited-method-crossrefs](https://github.com/mlprt/griffe-inherited-method-crossrefs)
+- **Extension name:** `griffe_inherited_method_crossrefs`
+
+---
+
+This extension replaces docstrings of inherited methods with cross-references to parent methods. For example, if a class `foo.Child` inherits the method `do_something` from `bar.Parent`, then in the generated documentation, the docstring of `Child.do_something` will appear similar to
+
+> Inherited from [bar.Parent](https://example.com/link/to/bar.Parent.do_something)
+
+whereas the docstring of `bar.Parent.do_something` will be unaffected.
+
+This is contrast to the official [`inherited-docstrings`](../official/inherited-docstrings.md) extension which simply attaches the docstring of the parent method to the subclass method, which means that modifying the subclass method docstring also modifies the parent method docstring (it's the same object).

docs/extensions/third-party/modernized-annotations.md

@@ -0,0 +1,9 @@
+# `griffe-modernized-annotations`
+
+- **PyPI**: [`griffe-modernized-annotations`](https://pypi.org/project/griffe-modernized-annotations/)
+- **GitHub**: [jonghwanhyeon/griffe-modernized-annotations](https://github.com/jonghwanhyeon/griffe-modernized-annotations)
+- **Extension name:** `griffe_modernized_annotations`
+
+---
+
+This extension modernizes type annotations by adopting [PEP 585](https://peps.python.org/pep-0585/) and [PEP 604](https://peps.python.org/pep-0604/). For example, it will transform `Union[A, B]` into `A | B`, and `List[str]` into `list[str]`.

mkdocs.yml

@@ -52,7 +52,24 @@ nav:
     - Development workflow: guide/contributors/workflow.md
     - Project architecture: guide/contributors/architecture.md
     - Coverage report: guide/contributors/coverage.md
-# TODO: Add an Extensions tab, with Built-in, Official and Third-Party sections.
+- Extensions:
+  - Built-in:
+    - extensions/built-in.md
+    - dataclasses: extensions/built-in/dataclasses.md
+  - Official:
+    - extensions/official.md
+    - inherited-docstrings: extensions/official/inherited-docstrings.md
+    - pydantic: extensions/official/pydantic.md
+    - sphinx: extensions/official/sphinx.md
+    - typingdoc: extensions/official/typingdoc.md
+    - warnings-deprecated: extensions/official/warnings-deprecated.md
+  - Third-party:
+    - extensions/third-party.md
+    - docstring-inheritance: extensions/third-party/docstring-inheritance.md
+    - fieldz: extensions/third-party/fieldz.md
+    - generics: extensions/third-party/generics.md
+    - inherited-method-crossrefs: extensions/third-party/inherited-method-crossrefs.md
+    - modernized-annotations: extensions/third-party/modernized-annotations.md
 - Reference:
   - reference.md
   - Command-line interface: reference/cli.md
@@ -195,6 +212,7 @@ plugins:
         # YORE: BOL 3.13: Replace `3.13` with `3` within line.
         - url: https://docs.python.org/3.13/objects.inv
           domains: [std, py]
+        - https://typing-extensions.readthedocs.io/en/latest/objects.inv
         paths: [src, scripts, .]
         options:
           docstring_options: