feat: Allow namespace packages for handlers

pawamoy · pawamoy · commit 39b046548f57 · 2020-10-11T22:41:42.000+02:00
diff --git a/docs/handlers/overview.md b/docs/handlers/overview.md
@@ -3,9 +3,9 @@
 A handler is what makes it possible to collect and render documentation for a particular language.
 It is composed of a collector and a renderer.
 See the documentation for
-[`BaseHandler`][mkdocstrings.handlers.BaseHandler],
-[`BaseCollector`][mkdocstrings.handlers.BaseCollector] and
-[`BaseRenderer`][mkdocstrings.handlers.BaseRenderer].
+[`BaseHandler`][mkdocstrings.handlers.base.BaseHandler],
+[`BaseCollector`][mkdocstrings.handlers.base.BaseCollector] and
+[`BaseRenderer`][mkdocstrings.handlers.base.BaseRenderer].
 
 ## Available handlers
 
diff --git a/docs/reference/handlers/__init__.md b/docs/reference/handlers/__init__.md
diff --git a/docs/reference/handlers/base.md b/docs/reference/handlers/base.md
@@ -0,0 +1,3 @@
+::: mkdocstrings.handlers.base
+    rendering:
+      show_root_heading: false
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -13,7 +13,7 @@ nav:
 
   - API Reference:
       - handlers:
-          - __init__.py: reference/handlers/__init__.md
+          - base.py: reference/handlers/base.md
           - python.py: reference/handlers/python.md
       - extension.py: reference/extension.md
       - plugin.py: reference/plugin.md
diff --git a/src/mkdocstrings/__init__.py b/src/mkdocstrings/__init__.py
diff --git a/src/mkdocstrings/extension.py b/src/mkdocstrings/extension.py
@@ -4,7 +4,7 @@
 The extension is composed of a Markdown [block processor](https://python-markdown.github.io/extensions/api/#blockparser)
 that matches indented blocks starting with a line like '::: identifier'.
 
-For each of these blocks, it uses a [handler][mkdocstrings.handlers.BaseHandler] to collect documentation about
+For each of these blocks, it uses a [handler][mkdocstrings.handlers.base.BaseHandler] to collect documentation about
 the given identifier and render it with Jinja templates.
 
 Both the collection and rendering process can be configured by adding YAML configuration under the "autodoc"
@@ -34,7 +34,7 @@
 from markdown.extensions import Extension
 from markdown.util import AtomicString
 
-from mkdocstrings.handlers import CollectionError, get_handler
+from mkdocstrings.handlers.base import CollectionError, get_handler
 from mkdocstrings.logging import get_logger
 
 log = get_logger(__name__)
diff --git a/src/mkdocstrings/handlers/base.py b/src/mkdocstrings/handlers/base.py
diff --git a/src/mkdocstrings/handlers/python.py b/src/mkdocstrings/handlers/python.py
@@ -12,7 +12,7 @@
 
 from markdown import Markdown
 
-from mkdocstrings.handlers import BaseCollector, BaseHandler, BaseRenderer, CollectionError
+from mkdocstrings.handlers.base import BaseCollector, BaseHandler, BaseRenderer, CollectionError
 from mkdocstrings.logging import get_logger
 
 log = get_logger(__name__)
@@ -23,7 +23,7 @@ class PythonRenderer(BaseRenderer):
     The class responsible for loading Jinja templates and rendering them.
 
     It defines some configuration options, implements the `render` method,
-    and overrides the `update_env` method of the [`BaseRenderer` class][mkdocstrings.handlers.BaseRenderer].
+    and overrides the `update_env` method of the [`BaseRenderer` class][mkdocstrings.handlers.base.BaseRenderer].
 
     Attributes:
         fallback_theme: The theme to fallback to.
@@ -91,7 +91,7 @@ class PythonCollector(BaseCollector):
     The class responsible for loading Jinja templates and rendering them.
 
     It defines some configuration options, implements the `render` method,
-    and overrides the `update_env` method of the [`BaseRenderer` class][mkdocstrings.handlers.BaseRenderer].
+    and overrides the `update_env` method of the [`BaseRenderer` class][mkdocstrings.handlers.base.BaseRenderer].
     """
 
     default_config: dict = {"filters": ["!^_[^_]"]}
diff --git a/src/mkdocstrings/plugin.py b/src/mkdocstrings/plugin.py
@@ -15,8 +15,8 @@
 and fixes them using the previously stored identifier-URL mapping.
 
 Once the documentation is built, the [`on_post_build` event hook](https://www.mkdocs.org/user-guide/plugins/#on_post_build)
-is triggered and calls the [`handlers.teardown()` method][mkdocstrings.handlers.teardown]. This method is used
-to teardown the [handlers][mkdocstrings.handlers] that were instantiated during documentation buildup.
+is triggered and calls the [`handlers.teardown()` method][mkdocstrings.handlers.base.teardown]. This method is used
+to teardown the handlers that were instantiated during documentation buildup.
 
 Finally, when serving the documentation, it can add directories to watch
 during the [`on_serve` event hook](https://www.mkdocs.org/user-guide/plugins/#on_serve).
@@ -34,7 +34,7 @@
 from mkdocs.structure.toc import AnchorLink
 
 from mkdocstrings.extension import MkdocstringsExtension
-from mkdocstrings.handlers import teardown
+from mkdocstrings.handlers.base import teardown
 from mkdocstrings.logging import get_logger
 from mkdocstrings.references import fix_refs
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+::: mkdocstrings.handlers.base`
	`2`	`+ rendering:`
	`3`	`+ show_root_heading: false`