refactor: Move modules into internal folder, expose API in top-level module

Also synchronize docs (objects inventory) with public API.

Author: pawamoy

CHANGELOG.md

@@ -589,7 +589,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Breaking changes
 
-- The signature of the [`format_signature` filter](https://mkdocstrings.github.io/python/reference/mkdocstrings_handlers/python/rendering/#mkdocstrings_handlers.python.rendering.do_format_signature) has changed.
+- The signature of the [`format_signature` filter][mkdocstrings_handlers.python.do_format_signature] has changed.
     If you override templates in your project to customize the output,
     make sure to update the following templates so that they use
     the new filter signature:

docs/insiders/changelog.md

@@ -81,6 +81,6 @@
 
 - Add [cross-references for type annotations in signatures](../usage/configuration/signatures.md#signature_crossrefs).
     Make sure to update your local templates as the signature of the
-    [`format_signature` filter][mkdocstrings_handlers.python.rendering.do_format_signature]
+    [`format_signature` filter][mkdocstrings_handlers.python.do_format_signature]
     has changed. The templates that must be updated:
     `class.html`, `expression.html`, `function.html` and `signature.html`.

docs/reference/api.md

@@ -5,3 +5,5 @@ hide:
 ---
 
 # ::: mkdocstrings_handlers.python
+    options:
+        show_submodules: true

mkdocs.yml

@@ -143,7 +143,7 @@ plugins:
 - autorefs
 - markdown-exec
 - section-index
-- coverage
+# - coverage
 - mkdocstrings:
     handlers:
       python:

pyproject.toml

@@ -86,6 +86,7 @@ maintain = [
     "yore>=0.3.3",
 ]
 ci = [
+    "blacK>=25.1",
     "duty>=1.6",
     "ruff>=0.4",
     "pytest>=8.2",
@@ -108,6 +109,7 @@ ci = [
     "mkdocs-material>=9.5",
     "pydantic>=2.10",
     "mkdocs-minify-plugin>=0.8",
+    "mkdocs-redirects>=1.2",
     "mkdocs-section-index>=0.3",
     # YORE: EOL 3.10: Remove line.
     "tomli>=2.0; python_version < '3.11'",

scripts/mkdocs_hooks.py

@@ -14,7 +14,7 @@
 try:
     from pydantic import TypeAdapter
 except ImportError:
-    TypeAdapter = None
+    TypeAdapter = None  # type: ignore[assignment,misc]
 
 
 _logger = get_plugin_logger(__name__)
@@ -38,9 +38,9 @@ class PythonHandlerSchema:
         _logger.debug("Generated JSON schema")
 
     autorefs = config["plugins"]["autorefs"]
-    for field in fields(PythonInputConfig):  # type: ignore[arg-type]
+    for field in fields(PythonInputConfig):
         if f"setting-{field.name}" not in autorefs._primary_url_map:
             _logger.warning(f"Handler setting `{field.name}` is not documented")
-    for field in fields(PythonInputOptions):  # type: ignore[arg-type]
+    for field in fields(PythonInputOptions):
         if f"option-{field.name}" not in autorefs._primary_url_map:
             _logger.warning(f"Configuration option `{field.name}` is not documented")

src/mkdocstrings_handlers/python/__init__.py

@@ -1,18 +1,70 @@
 """Python handler for mkdocstrings."""
 
 from mkdocstrings_handlers.python._internal.config import (
+    AutoStyleOptions,
+    GoogleStyleOptions,
+    Inventory,
+    NumpyStyleOptions,
+    PerStyleOptions,
     PythonConfig,
     PythonInputConfig,
     PythonInputOptions,
     PythonOptions,
+    SphinxStyleOptions,
+    SummaryOption,
 )
 from mkdocstrings_handlers.python._internal.handler import PythonHandler, get_handler
+from mkdocstrings_handlers.python._internal.rendering import (
+    AutorefsHook,
+    Order,
+    Tree,
+    do_as_attributes_section,
+    do_as_classes_section,
+    do_as_functions_section,
+    do_as_modules_section,
+    do_backlink_tree,
+    do_crossref,
+    do_filter_objects,
+    do_format_attribute,
+    do_format_code,
+    do_format_signature,
+    do_get_template,
+    do_multi_crossref,
+    do_order_members,
+    do_split_path,
+    do_stash_crossref,
+)
 
 __all__ = [
+    "AutoStyleOptions",
+    "AutorefsHook",
+    "GoogleStyleOptions",
+    "Inventory",
+    "NumpyStyleOptions",
+    "Order",
+    "PerStyleOptions",
     "PythonConfig",
     "PythonHandler",
     "PythonInputConfig",
     "PythonInputOptions",
     "PythonOptions",
+    "SphinxStyleOptions",
+    "SummaryOption",
+    "Tree",
+    "do_as_attributes_section",
+    "do_as_classes_section",
+    "do_as_functions_section",
+    "do_as_modules_section",
+    "do_backlink_tree",
+    "do_crossref",
+    "do_filter_objects",
+    "do_format_attribute",
+    "do_format_code",
+    "do_format_signature",
+    "do_get_template",
+    "do_multi_crossref",
+    "do_order_members",
+    "do_split_path",
+    "do_stash_crossref",
     "get_handler",
 ]