fixup! wip

Author: pawamoy

src/mkdocs_autorefs/plugin.py

@@ -13,10 +13,10 @@
 from __future__ import annotations
 
 import contextlib
-from dataclasses import dataclass
 import functools
 import logging
 from collections import defaultdict
+from dataclasses import dataclass
 from pathlib import PurePosixPath as URL  # noqa: N814
 from typing import TYPE_CHECKING, Any, Callable
 from urllib.parse import urlsplit
@@ -26,16 +26,16 @@
 from mkdocs.config.config_options import Type
 from mkdocs.plugins import BasePlugin, event_priority
 from mkdocs.structure.pages import Page
-from mkdocs.structure.files import Files
-from mkdocs.structure.nav import Section
-from jinja2.environment import Environment
 
-from mkdocs_autorefs.references import AutorefsExtension, URLAndTitle, _find_backlinks, fix_refs, relative_url
+from mkdocs_autorefs.references import AutorefsExtension, URLAndTitle, fix_refs, relative_url
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
+    from jinja2.environment import Environment
     from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs.structure.files import Files
+    from mkdocs.structure.nav import Section
     from mkdocs.structure.pages import Page
     from mkdocs.structure.toc import AnchorLink
 
@@ -48,15 +48,19 @@
     log = logging.getLogger(f"mkdocs.plugins.{__name__}")  # type: ignore[assignment]
 
 
-@dataclass(order=True)
+@dataclass(eq=True, frozen=True, order=True)
 class BacklinkCrumb:
+    """A navigation breadcrumb for a backlink."""
+
     title: str
     url: str
 
 
-@dataclass(order=True)
+@dataclass(eq=True, frozen=True, order=True)
 class Backlink:
-    crumbs: list[BacklinkCrumb]
+    """A backlink (list of breadcrumbs)."""
+
+    crumbs: tuple[BacklinkCrumb, ...]
 
 
 class AutorefsConfig(Config):
@@ -77,6 +81,17 @@ class AutorefsConfig(Config):
     When false and multiple URLs are found for an identifier, autorefs will log a warning and resolve to the first URL.
     """
 
+    link_titles = Type(bool, default=True)
+    """Whether to set titles on links.
+
+    When true, and when the link's text is different from the linked object's full id,
+    autorefs will set the title HTML attribute on the link, using the linked object's full id.
+    Such title attributes are displayed as tooltips when hovering over the links.
+
+    The presence of titles prevents the instant preview feature of Material for MkDocs from working,
+    so it might be useful to disable this option when using this Material for MkDocs feature.
+    """
+
 
 class AutorefsPlugin(BasePlugin[AutorefsConfig]):
     """The `autorefs` plugin for `mkdocs`.
@@ -164,26 +179,26 @@ def _record_backlink(self, identifier: str, backlink_type: str, backlink_anchor:
         if identifier in self._primary_url_map or identifier in self._secondary_url_map:
             self._backlinks[identifier][backlink_type].add(f"{page_url}#{backlink_anchor}")
 
-    def get_backlinks(self, *identifiers: str, from_url: str) -> dict[str, list[Backlink]]:
+    def get_backlinks(self, *identifiers: str, from_url: str) -> dict[str, set[Backlink]]:
         """Return the backlinks to an identifier relative to the given URL.
 
         Arguments:
             *identifiers: The identifiers to get backlinks for.
             from_url: The URL of the page where backlinks are rendered.
 
         Returns:
-            A dictionary of backlinks, with the type of reference as key and a list of backlinks as balue.
-            Each backlink is a list of (URL, title) tuples forming navigation breadcrumbs in reverse.
+            A dictionary of backlinks, with the type of reference as key and a set of backlinks as value.
+            Each backlink is a tuple of (URL, title) tuples forming navigation breadcrumbs.
         """
-        relative_backlinks: dict[str, list[Backlink]] = defaultdict(list)
-        for identifier in identifiers:
+        relative_backlinks: dict[str, set[Backlink]] = defaultdict(set)
+        for identifier in set(identifiers):
             backlinks = self._backlinks.get(identifier, {})
             for backlink_type, backlink_urls in backlinks.items():
                 for backlink_url in backlink_urls:
-                    relative_backlinks[backlink_type].append(self._nav(from_url, backlink_url))
+                    relative_backlinks[backlink_type].add(self._crumbs(from_url, backlink_url))
         return relative_backlinks
 
-    def _nav(self, from_url: str, backlink_url: str) -> Backlink:
+    def _crumbs(self, from_url: str, backlink_url: str) -> Backlink:
         backlink_page: Page = self._backlink_page_map[backlink_url]
         backlink_title = self._title_map[backlink_url]
         crumbs: list[BacklinkCrumb] = [
@@ -196,10 +211,11 @@ def _nav(self, from_url: str, backlink_url: str) -> Backlink:
             if url := getattr(page, "url", ""):
                 url = relative_url(from_url, url + "#")
             crumbs.append(BacklinkCrumb(page.title, url))
-        return Backlink(crumbs)
+        return Backlink(tuple(reversed(crumbs)))
 
     def register_anchor(
         self,
+        page: Page,
         identifier: str,
         anchor: str | None = None,
         *,
@@ -209,12 +225,12 @@ def register_anchor(
         """Register that an anchor corresponding to an identifier was encountered when rendering the page.
 
         Arguments:
+            page: The page where the anchor was found.
             identifier: The identifier to register.
             anchor: The anchor on the page, without `#`. If not provided, defaults to the identifier.
             title: The title of the anchor (optional).
             primary: Whether this anchor is the primary one for the identifier.
         """
-        page: Page = self.current_page  # type: ignore[assignment]
         url = f"{page.url}#{anchor or identifier}"
         url_map = self._primary_url_map if primary else self._secondary_url_map
         if identifier in url_map:
@@ -389,23 +405,24 @@ def on_page_content(self, html: str, page: Page, **kwargs: Any) -> str:  # noqa:
         if self.scan_toc:
             log.debug("Mapping identifiers to URLs for page %s", page.file.src_path)
             for item in page.toc.items:
-                self.map_urls(item)
+                self.map_urls(page, item)
         return html
 
-    def map_urls(self, anchor: AnchorLink) -> None:
+    def map_urls(self, page: Page, anchor: AnchorLink) -> None:
         """Recurse on every anchor to map its ID to its absolute URL.
 
         This method populates `self._primary_url_map` by side-effect.
 
         Arguments:
+            page: The page containing the anchors.
             anchor: The anchor to process and to recurse on.
         """
-        self.register_anchor(anchor.id, title=anchor.title, primary=True)
+        self.register_anchor(page, anchor.id, title=anchor.title, primary=True)
         for child in anchor.children:
-            self.map_urls(child)
+            self.map_urls(page, child)
 
     @event_priority(-50)  # Late, after mkdocstrings has finished loading inventories.
-    def on_env(self, env:  Environment, /, *, config: MkDocsConfig, files: Files) -> Environment:
+    def on_env(self, env: Environment, /, *, config: MkDocsConfig, files: Files) -> Environment:  # noqa: ARG002
         """Apply cross-references and collect backlinks.
 
         Hook for the [`on_env` event](https://www.mkdocs.org/user-guide/plugins/#on_env).
@@ -431,14 +448,26 @@ def on_env(self, env:  Environment, /, *, config: MkDocsConfig, files: Files) ->
                 log.debug("Applying cross-refs in page %s", file.page.file.src_path)
 
                 # YORE: Bump 2: Replace `, fallback=self.get_fallback_anchor` with `` within line.
-                url_mapper = functools.partial(self.get_item_url, from_url=file.page.url, fallback=self.get_fallback_anchor)
+                url_mapper = functools.partial(
+                    self.get_item_url,
+                    from_url=file.page.url,
+                    fallback=self.get_fallback_anchor,
+                )
                 backlink_recorder = functools.partial(self._record_backlink, page_url=file.page.url)
                 # YORE: Bump 2: Replace `, _legacy_refs=self.legacy_refs` with `` within line.
-                file.page.content, unmapped = fix_refs(file.page.content, url_mapper, record_backlink=backlink_recorder, _legacy_refs=self.legacy_refs)
+                file.page.content, unmapped = fix_refs(
+                    file.page.content,
+                    url_mapper,
+                    record_backlink=backlink_recorder,
+                    link_titles=self.config.link_titles,
+                    _legacy_refs=self.legacy_refs,
+                )
 
                 if unmapped and log.isEnabledFor(logging.WARNING):
                     for ref, context in unmapped:
                         message = f"from {context.filepath}:{context.lineno}: ({context.origin}) " if context else ""
-                        log.warning(f"{file.page.file.src_path}: {message}Could not find cross-reference target '{ref}'")
+                        log.warning(
+                            f"{file.page.file.src_path}: {message}Could not find cross-reference target '{ref}'",
+                        )
 
         return env

src/mkdocs_autorefs/references.py

@@ -388,15 +388,17 @@ def _find_backlinks(html: str) -> Iterator[tuple[str, str, str]]:
 def _tooltip(identifier: str, title: str | None) -> str:
     if title:
         if title == identifier:
-            return title
-        return f"{title} ({identifier})"
-    return identifier
+            return escape(title)
+        return escape(f"{title} ({identifier})")
+    return escape(identifier)
 
 
 def fix_ref(
     url_mapper: Callable[[str], URLAndTitle],
     unmapped: list[tuple[str, AutorefsHookInterface.Context | None]],
     record_backlink: Callable[[str, str, str], None] | None = None,
+    *,
+    link_titles: bool = True,
 ) -> Callable:
     """Return a `repl` function for [`re.sub`](https://docs.python.org/3/library/re.html#re.sub).
 
@@ -411,6 +413,7 @@ def fix_ref(
             such as [mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url][].
         unmapped: A list to store unmapped identifiers.
         record_backlink: A callable to record backlinks.
+        link_titles: Whether to set HTML titles on links.
 
     Returns:
         The actual function accepting a [`Match` object](https://docs.python.org/3/library/re.html#match-objects)
@@ -427,7 +430,11 @@ def inner(match: Match) -> str:
 
         identifiers = (identifier, slug) if slug else (identifier,)
 
-        if record_backlink and (backlink_type := attrs.get("backlink-type")) and (backlink_anchor := attrs.get("backlink-anchor")):
+        if (
+            record_backlink
+            and (backlink_type := attrs.get("backlink-type"))
+            and (backlink_anchor := attrs.get("backlink-anchor"))
+        ):
             record_backlink(identifier, backlink_type, backlink_anchor)
 
         try:
@@ -452,9 +459,8 @@ def inner(match: Match) -> str:
         class_attr = " ".join(classes)
         if remaining := attrs.remaining:
             remaining = f" {remaining}"
-        if optional and hover:
-            return f'<a class="{class_attr}" href="{escape(url)}"{remaining}>{title}</a>'
-        return f'<a class="{class_attr}" href="{escape(url)}"{remaining}>{title}</a>'
+        title_attr = f' title="{_tooltip(identifier, original_title)}"' if hover and link_titles else ""
+        return f'<a class="{class_attr}"{title_attr} href="{escape(url)}"{remaining}>{title}</a>'
 
     return inner
 
@@ -465,8 +471,9 @@ def fix_refs(
     # YORE: Bump 2: Remove line.
     *,
     record_backlink: Callable[[str, str, str], None] | None = None,
+    link_titles: bool = True,
     # YORE: Bump 2: Remove line.
-    _legacy_refs: bool = True,  # noqa: FBT001, FBT002
+    _legacy_refs: bool = True,
 ) -> tuple[str, list[tuple[str, AutorefsHookInterface.Context | None]]]:
     """Fix all references in the given HTML text.
 
@@ -475,12 +482,13 @@ def fix_refs(
         url_mapper: A callable that gets an object's site URL by its identifier,
             such as [mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url][].
         record_backlink: A callable to record backlinks.
+        link_titles: Whether to set HTML titles on links.
 
     Returns:
         The fixed HTML, and a list of unmapped identifiers (string and optional context).
     """
     unmapped: list[tuple[str, AutorefsHookInterface.Context | None]] = []
-    html = AUTOREF_RE.sub(fix_ref(url_mapper, unmapped, record_backlink), html)
+    html = AUTOREF_RE.sub(fix_ref(url_mapper, unmapped, record_backlink, link_titles=link_titles), html)
 
     # YORE: Bump 2: Remove block.
     if _legacy_refs:
@@ -552,9 +560,10 @@ def append(self, anchor: str) -> None:
         self.anchors.append(anchor)
 
     def flush(self, alias_to: str | None = None, title: str | None = None) -> None:
-        for anchor in self.anchors:
-            self.plugin.register_anchor(anchor, alias_to, title=title, primary=True)
-        self.anchors.clear()
+        if page := self.plugin.current_page:
+            for anchor in self.anchors:
+                self.plugin.register_anchor(page, anchor, alias_to, title=title, primary=True)
+            self.anchors.clear()
 
 
 class BacklinksTreeProcessor(Treeprocessor):
@@ -589,7 +598,7 @@ def _enhance_autorefs(self, parent: Element) -> None:
                 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
             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")

tests/helpers.py

@@ -0,0 +1,14 @@
+"""Helper functions for the tests."""
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File
+from mkdocs.structure.pages import Page
+
+
+def create_page(url: str) -> Page:
+    """Create a page with the given URL."""
+    return Page(
+        title=url,
+        file=File(url, "docs", "site", use_directory_urls=False),
+        config=MkDocsConfig(),
+    )