docs: Simplify API docs, fix a few things (stop using future annotations which are not well supported by pytkdocs)

Author: pawamoy

docs/reference.md

@@ -0,0 +1,4 @@
+::: mkdocstrings_handlers.python
+    options:
+        show_root_full_path: true
+

docs/usage.md

@@ -92,8 +92,9 @@ plugins:
 These options affect how the documentation is collected from sources and renderered:
 headings, members, docstrings, etc.
 
-::: mkdocstrings_handlers.python.handler.PythonHandler.default_config
+### ::: mkdocstrings_handlers.python.handler.PythonHandler.default_config
     options:
+      show_root_heading: false
       show_root_toc_entry: false
 
 ## Supported docstrings styles
@@ -134,7 +135,7 @@ For example:
 
         ```md
         ::: my_package.my_module
-            selection:
+            options:
               docstring_style: google  # this is the default
               docstring_options:
                 replace_admonitions: no 
@@ -153,7 +154,7 @@ For example:
 
         ```md
         ::: my_package.my_module
-            selection:
+            options:
               docstring_style: google  # this is the default
               docstring_options:
                 replace_admonitions: no 
@@ -170,7 +171,7 @@ For example:
     > 
     > ```md
     > ::: my_package.my_module
-    >     selection:
+    >     options:
     >       docstring_style: google  # this is the default
     >       docstring_options:
     >         replace_admonitions: no 
@@ -183,7 +184,7 @@ with the `replace_admonitions` option of the Google-style parser:
 
 ```yaml
 ::: my_package.my_module
-    selection:
+    options:
       docstring_style: google  # this is the default
       docstring_options:
         replace_admonitions: no 
@@ -196,10 +197,10 @@ Type annotations are read both in the code and in the docstrings.
 > EXAMPLE: **Example with a function**  
 > **Expand the source at the end to see the original code!**
 >
-> ::: snippets.function_annotations_google:my_function
->     rendering:
->       show_root_heading: no
->       show_root_toc_entry: no
+> ### ::: snippets.function_annotations_google:my_function
+>     options:
+>       show_root_heading: false
+>       show_root_toc_entry: false
 
 ### Numpy-style
 

mkdocs.yml

@@ -20,9 +20,7 @@ nav:
   - Changelog: changelog.md
   - Credits: credits.md
   - License: license.md
-# defer to gen-files + literate-nav
-- API reference:
-  - mkdocstrings-python (legacy): reference/
+- API reference: reference.md
 - Development:
   - Contributing: contributing.md
   - Code of Conduct: code_of_conduct.md
@@ -103,9 +101,6 @@ markdown_extensions:
 plugins:
 - search
 - markdown-exec
-- gen-files:
-    scripts:
-    - scripts/gen_ref_nav.py
 - literate-nav:
     nav_file: SUMMARY.md
 - coverage
@@ -122,16 +117,17 @@ plugins:
             ignore_init_summary: true
           docstring_section_style: list
           filters: ["!^_"]
+          group_by_category: true
           heading_level: 1
           inherited_members: true
           merge_init_into_class: true
           separate_signature: true
+          show_category_heading: true
           show_root_heading: true
           show_root_full_path: false
           show_signature_annotations: true
           show_source: true
-          show_symbol_type_heading: true
-          show_symbol_type_toc: true
+          show_submodules: false
           signature_crossrefs: true
           summary: true
 - git-revision-date-localized:

pyproject.toml

@@ -95,9 +95,7 @@ dev-dependencies = [
     "markdown-exec>=1.8",
     "mkdocs>=1.6",
     "mkdocs-coverage>=1.0",
-    "mkdocs-gen-files>=0.5",
     "mkdocs-git-revision-date-localized-plugin>=1.2",
-    "mkdocs-literate-nav>=0.6",
     "mkdocs-material>=9.5",
     "mkdocs-minify-plugin>=0.8",
     "tomli>=2.0; python_version < '3.11'",

scripts/gen_ref_nav.py

@@ -1,12 +1,11 @@
 """Debugging utilities."""
 
-from __future__ import annotations
-
 import os
 import platform
 import sys
 from dataclasses import dataclass
 from importlib import metadata
+from typing import List, Tuple
 
 
 @dataclass
@@ -39,13 +38,13 @@ class Environment:
     """Python interpreter version."""
     platform: str
     """Operating System."""
-    packages: list[Package]
+    packages: List[Package]
     """Installed packages."""
-    variables: list[Variable]
+    variables: List[Variable]
     """Environment variables."""
 
 
-def _interpreter_name_version() -> tuple[str, str]:
+def _interpreter_name_version() -> Tuple[str, str]:
     if hasattr(sys, "implementation"):
         impl = sys.implementation.version
         version = f"{impl.major}.{impl.minor}.{impl.micro}"

src/mkdocstrings_handlers/python/debug.py

@@ -3,16 +3,20 @@
 It collects data with [`pytkdocs`](https://github.com/pawamoy/pytkdocs).
 """
 
-from __future__ import annotations
-
 import json
 import os
 import posixpath
 import sys
 import traceback
 from collections import ChainMap
 from subprocess import PIPE, Popen
-from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, Iterator, Mapping, MutableMapping
+from typing import Any, BinaryIO, ClassVar, Iterator, List, Mapping, MutableMapping, Optional, Tuple
+
+from markdown import Markdown
+from mkdocstrings.extension import PluginError
+from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem
+from mkdocstrings.inventory import Inventory
+from mkdocstrings.loggers import get_logger
 
 from mkdocstrings_handlers.python.rendering import (
     do_brief_xref,
@@ -22,14 +26,6 @@
     sort_object,
 )
 
-from mkdocstrings.extension import PluginError
-from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem
-from mkdocstrings.inventory import Inventory
-from mkdocstrings.loggers import get_logger
-
-if TYPE_CHECKING:
-    from markdown import Markdown
-
 # TODO: add a deprecation warning once the new handler handles 95% of use-cases
 
 logger = get_logger(__name__)
@@ -123,9 +119,9 @@ class PythonHandler(BaseHandler):
     def __init__(
         self,
         *args: Any,
-        setup_commands: list[str] | None = None,
-        config_file_path: str | None = None,
-        paths: list[str] | None = None,
+        setup_commands: Optional[List[str]] = None,
+        config_file_path: Optional[str] = None,
+        paths: Optional[List[str]] = None,
         **kwargs: Any,
     ) -> None:
         """Initialize the handler.
@@ -187,8 +183,8 @@ def __init__(
         else:
             cmd = [sys.executable, "-m", "pytkdocs", "--line-by-line"]
 
-        self.process = Popen(
-            cmd,  # noqa: S603
+        self.process = Popen(  # noqa: S603
+            cmd,
             universal_newlines=True,
             stdout=PIPE,
             stdin=PIPE,
@@ -202,9 +198,9 @@ def load_inventory(
         cls,
         in_file: BinaryIO,
         url: str,
-        base_url: str | None = None,
+        base_url: Optional[str] = None,
         **kwargs: Any,  # noqa: ARG003
-    ) -> Iterator[tuple[str, str]]:
+    ) -> Iterator[Tuple[str, str]]:
         """Yield items and their URLs from an inventory file streamed from `in_file`.
 
         This implements mkdocstrings' `load_inventory` "protocol" (see plugin.py).
@@ -328,7 +324,7 @@ def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:  # noqa
             **{"config": final_config, data["category"]: data, "heading_level": heading_level, "root": True},
         )
 
-    def get_anchors(self, data: CollectorItem) -> tuple[str, ...]:  # noqa: D102 (ignore missing docstring)
+    def get_anchors(self, data: CollectorItem) -> Tuple[str, ...]:  # noqa: D102 (ignore missing docstring)
         try:
             return (data["path"],)
         except KeyError:
@@ -344,10 +340,10 @@ def update_env(self, md: Markdown, config: dict) -> None:  # noqa: D102 (ignore
 
 def get_handler(
     theme: str,
-    custom_templates: str | None = None,
-    setup_commands: list[str] | None = None,
-    config_file_path: str | None = None,
-    paths: list[str] | None = None,
+    custom_templates: Optional[str] = None,
+    setup_commands: Optional[List[str]] = None,
+    config_file_path: Optional[str] = None,
+    paths: Optional[List[str]] = None,
     **config: Any,  # noqa: ARG001
 ) -> PythonHandler:
     """Simply return an instance of `PythonHandler`.

src/mkdocstrings_handlers/python/handler.py

@@ -1,17 +1,12 @@
 """This module implements rendering utilities."""
 
-from __future__ import annotations
-
 import sys
-from typing import TYPE_CHECKING, Any, Callable
+from typing import Any, Callable
 
 from markupsafe import Markup
-
+from mkdocstrings.handlers.base import CollectorItem
 from mkdocstrings.loggers import get_logger
 
-if TYPE_CHECKING:
-    from mkdocstrings.handlers.base import CollectorItem
-
 log = get_logger(__name__)
 
 

src/mkdocstrings_handlers/python/rendering.py

@@ -1,11 +1,12 @@
 """Tests for the `collector` module."""
+
 from unittest import mock
 
 import pytest
-from mkdocstrings_handlers.python import get_handler
-
 from mkdocstrings.handlers.base import CollectionError
 
+from mkdocstrings_handlers.python import get_handler
+
 
 @pytest.mark.parametrize(
     ("retval", "exp_res"),