refactor: Prepare feature for ordering by __all__ value

pawamoy · pawamoy · commit bfb5b303f4ea · 2025-03-22T13:45:53.000+01:00
Issue-219: #219
diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md
@@ -2,6 +2,10 @@
 
 ## mkdocstrings-python Insiders
 
+### 1.12.0 <small>March 22, 2025</small> { id="1.12.0" }
+
+- [Ordering method: `__all__`][option-members_order]
+
 ### 1.11.0 <small>March 20, 2025</small> { id="1.11.0" }
 
 - [Filtering method: `public`][option-filters-public]
diff --git a/docs/insiders/goals.yml b/docs/insiders/goals.yml
@@ -48,3 +48,6 @@ goals:
     - name: "Filtering method: `public`"
       ref: /usage/configuration/members/#option-filters-public
       since: 2025/03/20
+    - name: "Ordering method: `__all__`"
+      ref: /usage/configuration/members/#option-members_order
+      since: 2025/03/22
diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md
@@ -264,13 +264,14 @@ class Main(Base):
 [](){#option-members_order}
 ## `members_order`
 
-- **:octicons-package-24: Type [`str`][] :material-equal: `"alphabetical"`{ title="default value" }**
+- **:octicons-package-24: Type `str | list[str]` :material-equal: `"alphabetical"`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
 The members ordering to use. Possible values:
 
-- `alphabetical`: order by the members names.
-- `source`: order members as they appear in the source file.
+- `__all__` ([:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash; [:octicons-tag-24: Insiders 1.12.0](../../insiders/changelog.md#1.12.0)): Order according to `__all__` attributes. Since classes do not define `__all__` attributes, you can specify a second ordering method by using a list.
+- `alphabetical`: Order by the members names.
+- `source`: Order members as they appear in the source file.
 
 The order applies for all members, recursively.
 The order will be ignored for members that are explicitely sorted using the [`members`][] option.
@@ -292,6 +293,12 @@ plugins:
       members_order: source
 ```
 
+```md title="or in docs/some_page.md (local configuration)"
+::: package.module
+    options:
+      members_order: [__all__, source]
+```
+
 ```python title="package/module.py"
 """Module docstring."""
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -33,7 +33,7 @@ classifiers = [
 dependencies = [
     "mkdocstrings>=0.28.3",
     "mkdocs-autorefs>=1.4",
-    "griffe>=0.49",
+    "griffe>=1.6.2",
     "typing-extensions>=4.0; python_version < '3.11'",
 ]
 
diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py
@@ -9,6 +9,8 @@
 
 from mkdocstrings import get_logger
 
+from mkdocstrings_handlers.python._internal.rendering import Order  # noqa: TC001
+
 # YORE: EOL 3.10: Replace block with line 2.
 if sys.version_info >= (3, 11):
     from typing import Self
@@ -520,13 +522,18 @@ class PythonInputOptions:
     ] = None
 
     members_order: Annotated[
-        Literal["alphabetical", "source"],
+        Order | list[Order],
         _Field(
             group="members",
             description="""The members ordering to use.
 
-            - `alphabetical`: order by the members names,
+            - `__all__`: order members according to `__all__` module attributes, if declared;
+            - `alphabetical`: order members alphabetically;
             - `source`: order members as they appear in the source file.
+
+            Since `__all__` is a module-only attribute, it can't be used to sort class members,
+            therefore the `members_order` option accepts a list of ordering methods,
+            indicating ordering preferences.
             """,
         ),
     ] = "alphabetical"
diff --git a/src/mkdocstrings_handlers/python/_internal/rendering.py b/src/mkdocstrings_handlers/python/_internal/rendering.py
@@ -9,6 +9,7 @@
 import sys
 import warnings
 from collections import defaultdict
+from contextlib import suppress
 from dataclasses import replace
 from functools import lru_cache
 from pathlib import Path
@@ -56,12 +57,22 @@ def _sort_key_source(item: CollectorItem) -> float:
     return item.lineno if item.lineno is not None else float("inf")
 
 
-Order = Literal["alphabetical", "source"]
-"""Ordering methods."""
+def _sort__all__(item: CollectorItem) -> float:  # noqa: ARG001
+    raise ValueError("Not implemented in public version of mkdocstrings-python")
 
-_order_map = {
+
+Order = Literal["__all__", "alphabetical", "source"]
+"""Ordering methods.
+
+- `__all__`: order members according to `__all__` module attributes, if declared;
+- `alphabetical`: order members alphabetically;
+- `source`: order members as they appear in the source file.
+"""
+
+_order_map: dict[str, Callable[[Object | Alias], str | float]] = {
     "alphabetical": _sort_key_alphabetical,
     "source": _sort_key_source,
+    "__all__": _sort__all__,
 }
 
 
@@ -245,7 +256,7 @@ def do_format_attribute(
 
 def do_order_members(
     members: Sequence[Object | Alias],
-    order: Order,
+    order: Order | list[Order],
     members_list: bool | list[str] | None,
 ) -> Sequence[Object | Alias]:
     """Order members given an ordering method.
@@ -265,7 +276,12 @@ def do_order_members(
             if name in members_dict:
                 sorted_members.append(members_dict[name])
         return sorted_members
-    return sorted(members, key=_order_map[order])
+    if isinstance(order, str):
+        order = [order]
+    for method in order:
+        with suppress(ValueError):
+            return sorted(members, key=_order_map[method])
+    return members
 
 
 # YORE: Bump 2: Remove block.
