docs: Document public-redundant-aliases and public-wildcard-imports e…

…xtensions

docs/extensions/official.md

@@ -6,6 +6,8 @@ Available official extensions:
 
 - [`autodocstringstyle`](official/autodocstringstyle.md): Set docstring style to `auto` for external packages. [:octicons-heart-fill-24:{ .pulse } Sponsors only](../insiders/index.md){ .insiders }
 - [`inherited-docstrings`](official/inherited-docstrings.md): Inherit docstrings from parent classes.
+- [`public-redundant-aliases`](official/public-redundant-aliases.md): Mark objects imported with redundant aliases as public. [:octicons-heart-fill-24:{ .pulse } Sponsors only](../insiders/index.md){ .insiders }
+- [`public-wildcard-imports`](official/public-wildcard-imports.md): Mark wildcard imported objects as public. [:octicons-heart-fill-24:{ .pulse } Sponsors only](../insiders/index.md){ .insiders }
 - [`pydantic`](official/pydantic.md): Support for [Pydantic](https://docs.pydantic.dev/latest/) models. [:octicons-heart-fill-24:{ .pulse } Sponsors only](../insiders/index.md){ .insiders }
 - [`runtime-objects`](official/runtime-objects.md): Access runtime objects corresponding to each loaded Griffe object through their `extra` attribute. [: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 }

docs/extensions/official/public-redundant-aliases.md

@@ -0,0 +1,12 @@
+# `griffe-public-redundant-aliases`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders }
+
+- **PyPI**: [`griffe-public-redundant-aliases`](https://pypi.org/project/griffe-public-redundant-aliases/)
+- **GitHub**: [mkdocstrings/griffe-public-redundant-aliases](https://github.com/mkdocstrings/griffe-public-redundant-aliases)
+- **Documentation:** [mkdocstrings.github.io/griffe-public-redundant-aliases](https://mkdocstrings.github.io/griffe-public-redundant-aliases)
+- **Extension name:** `griffe_public_redundant_aliases`
+
+---
+
+This extension marks every objects that was imported with a redundant alias as public. See our documentation on the [redundant aliases convention](../../guide/users/recommendations/public-apis.md#redundant-aliases).

docs/extensions/official/public-wildcard-imports.md

@@ -0,0 +1,12 @@
+# `griffe-public-wildcard-imports`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders }
+
+- **PyPI**: [`griffe-public-wildcard-imports`](https://pypi.org/project/griffe-public-wildcard-imports/)
+- **GitHub**: [mkdocstrings/griffe-public-wildcard-imports](https://github.com/mkdocstrings/griffe-public-wildcard-imports)
+- **Documentation:** [mkdocstrings.github.io/griffe-public-wildcard-imports](https://mkdocstrings.github.io/griffe-public-wildcard-imports)
+- **Extension name:** `griffe_public_wildcard_imports`
+
+---
+
+This extension marks every objects that was imported with a wildcard import as public. See our documentation on the [wildcard imports convention](../../guide/users/recommendations/public-apis.md#wildcard-imports).

docs/guide/users/recommendations/public-apis.md

@@ -124,7 +124,9 @@ Note that the wildcard imports logic stays the same, and imports either all obje
 ---
 
 > GRIFFE: **Our recommendation — Use the underscore prefix and `__all__` conventions.**
-> Use both the underscore prefix convention for consistent naming at module and class levels, and the `__all__` convention for declaring your public API. We do not recommend using the redundant aliases convention, because it doesn't provide any information at runtime. We do not recommend the wildcard import convention either, for the same reason and [for additional reasons mentioned here](python-code.md#avoid-wildcard-imports). Our recommendation matches [PEP 8](https://peps.python.org/pep-0008/#public-and-internal-interfaces):
+> Use both the underscore prefix convention for consistent naming at module and class levels, and the `__all__` convention for declaring your public API. We do not recommend using the redundant aliases convention, because it doesn't provide any information at runtime. We do not recommend the wildcard import convention either, for the same reason and [for additional reasons mentioned here](python-code.md#avoid-wildcard-imports). We still provide the [`griffe-public-redundant-aliases`](https://mkdocstrings.github.io/griffe-public-redundant-aliases/) and [`griffe-public-wildcard-imports`](https://mkdocstrings.github.io/griffe-public-wildcard-imports/) extensions for those who would still like to rely on these conventions.
+>
+> Our recommendation matches [PEP 8](https://peps.python.org/pep-0008/#public-and-internal-interfaces):
 >
 > > To better support introspection, modules should explicitly declare the names in their public API using the `__all__` attribute. Setting `__all__` to an empty list indicates that the module has no public API.
 >

docs/insiders/index.md

@@ -61,6 +61,8 @@ data_source = [
     ("mkdocstrings/griffe2md", "https://mkdocstrings.github.io/griffe2md/", "insiders/goals.yml"),
     ("mkdocstrings/griffe-autodocstringstyle", "https://mkdocstrings.github.io/griffe-autodocstringstyle/", "insiders/goals.yml"),
     ("mkdocstrings/griffe-inherited-docstrings", "https://mkdocstrings.github.io/griffe-inherited-docstrings/", "insiders/goals.yml"),
+    ("mkdocstrings/griffe-public-redundant-aliases", "https://mkdocstrings.github.io/griffe-public-redundant-aliases/", "insiders/goals.yml"),
+    ("mkdocstrings/griffe-public-wildcard-imports", "https://mkdocstrings.github.io/griffe-public-wildcard-imports/", "insiders/goals.yml"),
     ("mkdocstrings/griffe-pydantic", "https://mkdocstrings.github.io/griffe-pydantic/", "insiders/goals.yml"),
     ("mkdocstrings/griffe-runtime-objects", "https://mkdocstrings.github.io/griffe-runtime-objects/", "insiders/goals.yml"),
     ("mkdocstrings/griffe-sphinx", "https://mkdocstrings.github.io/griffe-sphinx/", "insiders/goals.yml"),

mkdocs.yml

@@ -62,6 +62,8 @@ nav:
     - extensions/official.md
     - autodocstringstyle: extensions/official/autodocstringstyle.md
     - inherited-docstrings: extensions/official/inherited-docstrings.md
+    - public-redundant-aliases: extensions/official/public-redundant-aliases.md
+    - public-wildcard-imports: extensions/official/public-wildcard-imports.md
     - pydantic: extensions/official/pydantic.md
     - runtime-objects: extensions/official/runtime-objects.md
     - sphinx: extensions/official/sphinx.md