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

Author: pawamoy

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"

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",
+]

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)