refactor: Move code to internal folder, expose public API in top-level module, document all public objects

Author: pawamoy

Diff for: pyproject.toml

@@ -49,7 +49,7 @@ Discussions = "https://github.com/mkdocstrings/autorefs/discussions"
 Gitter = "https://gitter.im/mkdocstrings/autorefs"
 
 [project.entry-points."mkdocs.plugins"]
-autorefs = "mkdocs_autorefs.plugin:AutorefsPlugin"
+autorefs = "mkdocs_autorefs:AutorefsPlugin"
 
 [tool.pdm.version]
 source = "call"

Diff for: src/mkdocs_autorefs/__init__.py

@@ -5,4 +5,33 @@
 
 from __future__ import annotations
 
-__all__: list[str] = []
+from mkdocs_autorefs._internal.backlinks import Backlink, BacklinkCrumb, BacklinksTreeProcessor
+from mkdocs_autorefs._internal.plugin import AutorefsConfig, AutorefsPlugin
+from mkdocs_autorefs._internal.references import (
+    AUTO_REF_RE,
+    AUTOREF_RE,
+    AnchorScannerTreeProcessor,
+    AutorefsExtension,
+    AutorefsHookInterface,
+    AutorefsInlineProcessor,
+    fix_ref,
+    fix_refs,
+    relative_url,
+)
+
+__all__: list[str] = [
+    "AUTOREF_RE",
+    "AUTO_REF_RE",
+    "AnchorScannerTreeProcessor",
+    "AutorefsConfig",
+    "AutorefsExtension",
+    "AutorefsHookInterface",
+    "AutorefsInlineProcessor",
+    "AutorefsPlugin",
+    "Backlink",
+    "BacklinkCrumb",
+    "BacklinksTreeProcessor",
+    "fix_ref",
+    "fix_refs",
+    "relative_url",
+]

Diff for: src/mkdocs_autorefs/backlinks.py renamed to src/mkdocs_autorefs/_internal/backlinks.py

@@ -1,4 +1,4 @@
-"""Backlinks module."""
+# Backlinks module.
 
 from __future__ import annotations
 
@@ -14,30 +14,33 @@
 
     from markdown import Markdown
 
-    from mkdocs_autorefs.plugin import AutorefsPlugin
+    from mkdocs_autorefs._internal.plugin import AutorefsPlugin
 
 try:
     from mkdocs.plugins import get_plugin_logger
 
-    log = get_plugin_logger(__name__)
+    _log = get_plugin_logger(__name__)
 except ImportError:
     # TODO: remove once support for MkDocs <1.5 is dropped
-    log = logging.getLogger(f"mkdocs.plugins.{__name__}")  # type: ignore[assignment]
+    _log = logging.getLogger(f"mkdocs.plugins.{__name__}")  # type: ignore[assignment]
 
 
 @dataclass(eq=True, frozen=True, order=True)
 class BacklinkCrumb:
     """A navigation breadcrumb for a backlink."""
 
     title: str
+    """The title of the page."""
     url: str
+    """The URL of the page."""
 
 
 @dataclass(eq=True, frozen=True, order=True)
 class Backlink:
     """A backlink (list of breadcrumbs)."""
 
     crumbs: tuple[BacklinkCrumb, ...]
+    """The list of breadcrumbs."""
 
 
 class BacklinksTreeProcessor(Treeprocessor):
@@ -47,7 +50,10 @@ class BacklinksTreeProcessor(Treeprocessor):
     """
 
     name: str = "mkdocs-autorefs-backlinks"
+    """The name of the tree processor."""
     initial_id: str | None = None
+    """The initial heading ID."""
+
     _htags: ClassVar[set[str]] = {"h1", "h2", "h3", "h4", "h5", "h6"}
 
     def __init__(self, plugin: AutorefsPlugin, md: Markdown | None = None) -> None:
@@ -57,25 +63,30 @@ def __init__(self, plugin: AutorefsPlugin, md: Markdown | None = None) -> None:
             plugin: A reference to the autorefs plugin, to use its `register_anchor` method.
         """
         super().__init__(md)
-        self.plugin = plugin
-        self.last_heading_id: str | None = None
+        self._plugin = plugin
+        self._last_heading_id: str | None = None
+
+    def run(self, root: Element) -> None:
+        """Run the tree processor.
 
-    def run(self, root: Element) -> None:  # noqa: D102
-        if self.plugin.current_page is not None:
-            self.last_heading_id = self.initial_id
+        Arguments:
+            root: The root element of the document.
+        """
+        if self._plugin.current_page is not None:
+            self._last_heading_id = self.initial_id
             self._enhance_autorefs(root)
 
     def _enhance_autorefs(self, parent: Element) -> None:
         for el in parent:
             if el.tag == "a":  # Markdown anchor.
                 if not (el.text or el.get("href") or (el.tail and el.tail.strip())) and (anchor_id := el.get("id")):
-                    self.last_heading_id = anchor_id
+                    self._last_heading_id = anchor_id
             elif el.tag in self._htags:  # Heading.
-                self.last_heading_id = el.get("id")
+                self._last_heading_id = el.get("id")
             elif el.tag == "autoref":
                 if "backlink-type" not in el.attrib:
                     el.set("backlink-type", "referenced-by")
-                if "backlink-anchor" not in el.attrib and self.last_heading_id:
-                    el.set("backlink-anchor", self.last_heading_id)
+                if "backlink-anchor" not in el.attrib and self._last_heading_id:
+                    el.set("backlink-anchor", self._last_heading_id)
             else:
                 self._enhance_autorefs(el)

Diff for: src/mkdocs_autorefs/_internal/plugin.py

@@ -152,10 +152,15 @@ def test_inventory_matches_api(
     not_in_api = []
     public_api_paths = {obj.path for obj in public_objects}
     public_api_paths.add("mkdocs_autorefs")
+    ignore = {"mkdocs_autorefs.plugin", "mkdocs_autorefs.references"}
     for item in inventory.values():
         if item.domain == "py" and "(" not in item.name:
             obj = loader.modules_collection[item.name]
-            if obj.path not in public_api_paths and not any(path in public_api_paths for path in obj.aliases):
+            if (
+                obj.path not in ignore
+                and obj.path not in public_api_paths
+                and not any(path in public_api_paths for path in obj.aliases)
+            ):
                 not_in_api.append(item.name)
     msg = "Inventory objects not in public API (try running `make run mkdocs build`):\n{paths}"
     assert not not_in_api, msg.format(paths="\n".join(sorted(not_in_api)))
@@ -174,4 +179,4 @@ def _modules(obj: griffe.Module) -> Iterator[griffe.Module]:
             yield from _modules(member)
 
     for obj in _modules(internal_api):
-        assert not obj.docstring
+        assert not obj.docstring, f"Object {obj.path} has a docstring."

Diff for: src/mkdocs_autorefs/_internal/references.py

@@ -6,9 +6,8 @@
 
 from markdown import Markdown
 
-from mkdocs_autorefs.backlinks import Backlink, BacklinkCrumb
-from mkdocs_autorefs.plugin import AutorefsPlugin
-from mkdocs_autorefs.references import AUTOREF_RE, AutorefsExtension, _html_attrs_parser
+from mkdocs_autorefs import AUTOREF_RE, AutorefsExtension, AutorefsPlugin, Backlink, BacklinkCrumb
+from mkdocs_autorefs._internal.references import _html_attrs_parser
 from tests.helpers import create_page
 
 

Diff for: src/mkdocs_autorefs/plugin.py

@@ -9,8 +9,7 @@
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.theme import Theme
 
-from mkdocs_autorefs.plugin import AutorefsConfig, AutorefsPlugin
-from mkdocs_autorefs.references import fix_refs
+from mkdocs_autorefs import AutorefsConfig, AutorefsPlugin, fix_refs
 from tests.helpers import create_page
 
 

Diff for: src/mkdocs_autorefs/references.py

@@ -8,8 +8,7 @@
 import markdown
 import pytest
 
-from mkdocs_autorefs.plugin import AutorefsPlugin
-from mkdocs_autorefs.references import AutorefsExtension, AutorefsHookInterface, fix_refs, relative_url
+from mkdocs_autorefs import AutorefsExtension, AutorefsHookInterface, AutorefsPlugin, fix_refs, relative_url
 from tests.helpers import create_page
 
 if TYPE_CHECKING: