wip

Author: pawamoy

mkdocs.yml

@@ -40,6 +40,7 @@ theme:
   - content.tooltips
   - navigation.footer
   - navigation.indexes
+  - navigation.instant.preview
   - navigation.sections
   - navigation.tabs
   - navigation.tabs.sticky

src/mkdocs_autorefs/plugin.py

@@ -15,6 +15,7 @@
 import contextlib
 import functools
 import logging
+from collections import defaultdict
 from pathlib import PurePosixPath as URL  # noqa: N814
 from typing import TYPE_CHECKING, Any, Callable
 from urllib.parse import urlsplit
@@ -24,8 +25,11 @@
 from mkdocs.config.config_options import Type
 from mkdocs.plugins import BasePlugin
 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, fix_refs, relative_url
+from mkdocs_autorefs.references import AutorefsExtension, URLAndTitle, _find_backlinks, fix_refs, relative_url
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -43,6 +47,15 @@
     log = logging.getLogger(f"mkdocs.plugins.{__name__}")  # type: ignore[assignment]
 
 
+# TODO: BACKLINKS: Record URLs directly. It's wrong to record ids and use them later
+# to fetch all associated URLs: not all these URLs link to the cross-ref'd object.
+# Also, don't store URLs + titles, only store URLs in maps, and store titles in a separate dict.
+# Also also, backlinks should be fetched for all aliases of a given identifier,
+# not just for this specific identifier. For example, mkdocstrings-python will create
+# an autoref for a parameter default value with `used-by` type and `object.canonical.path` as id,
+# But if we don't render the object with this canonical path but instead `object.path`,
+# then we won't find the backlinks for it.
+
 class AutorefsConfig(Config):
     """Configuration options for the `autorefs` plugin."""
 
@@ -76,7 +89,7 @@ class AutorefsPlugin(BasePlugin[AutorefsConfig]):
     """
 
     scan_toc: bool = True
-    current_page: str | None = None
+    current_page: Page | None = None
     # YORE: Bump 2: Remove line.
     legacy_refs: bool = True
 
@@ -111,7 +124,9 @@ def __init__(self) -> None:
         # This logic unfolds in `_get_item_url`.
         self._primary_url_map: dict[str, list[str]] = {}
         self._secondary_url_map: dict[str, list[str]] = {}
+        self._title_map: dict[str, str] = {}
         self._abs_url_map: dict[str, str] = {}
+        self._backlinks: dict[str, dict[str, set[str]]] = defaultdict(lambda: defaultdict(set))
         # YORE: Bump 2: Remove line.
         self._get_fallback_anchor: Callable[[str], tuple[str, ...]] | None = None
 
@@ -133,22 +148,68 @@ def get_fallback_anchor(self, value: Callable[[str], tuple[str, ...]] | None) ->
                 stacklevel=2,
             )
 
-    def register_anchor(self, page: str, identifier: str, anchor: str | None = None, *, primary: bool = True) -> None:
+    def _record_backlink(self, identifier: str, backlink_type: str, backlink_url: str) -> None:
+        """Record a backlink.
+
+        Arguments:
+            identifier: The target identifier.
+            backlink_type: The type of backlink.
+            backlink_url: The URL of the backlink.
+        """
+        if identifier in self._primary_url_map or identifier in self._secondary_url_map:
+            self._backlinks[identifier][backlink_type].add(backlink_url)
+
+    def get_relative_backlinks(self, *identifiers: str, from_url: str) -> dict[str, set[URLAndTitle]]:
+        """Return the backlinks to an identifier relative to the current page.
+
+        Arguments:
+            *identifiers: The identifiers to get backlinks for.
+            from_url: The URL of the current page.
+
+        Returns:
+            A dictionary of backlinks, with the type of reference as key and a list of URLs as value.
+        """
+        relative_backlinks: dict[str, set[URLAndTitle]] = defaultdict(set)
+        for identifier in identifiers:
+            backlinks = self._backlinks.get(identifier, {})
+            for backlink_type, backlink_urls in backlinks.items():
+                for backlink_url in backlink_urls:
+                    relative_backlinks[backlink_type].add((relative_url(from_url, backlink_url), self._title_map[backlink_url]))
+        return relative_backlinks
+
+    def _breadcrumbs(self, page: Page | Section, title: str) -> str:
+        breadcrumbs = [title, page.title]
+        while page.parent:
+            page = page.parent
+            breadcrumbs.append(page.title)
+        return " ❭ ".join(reversed(breadcrumbs))
+
+    def register_anchor(
+        self,
+        identifier: str,
+        anchor: str | None = None,
+        *,
+        title: str | None = None,
+        primary: bool = True,
+    ) -> None:
         """Register that an anchor corresponding to an identifier was encountered when rendering the page.
 
         Arguments:
-            page: The relative URL of the current page. Examples: `'foo/bar/'`, `'foo/index.html'`
             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_anchor = f"{page}#{anchor or identifier}"
+        page_anchor = f"{self.current_page.url}#{anchor or identifier}"
         url_map = self._primary_url_map if primary else self._secondary_url_map
         if identifier in url_map:
             if page_anchor not in url_map[identifier]:
                 url_map[identifier].append(page_anchor)
         else:
             url_map[identifier] = [page_anchor]
+        if title and page_anchor not in self._title_map:
+            title = self._breadcrumbs(self.current_page, title) if self.current_page else title
+            self._title_map[page_anchor] = title
 
     def register_url(self, identifier: str, url: str) -> None:
         """Register that the identifier should be turned into a link to this URL.
@@ -240,7 +301,7 @@ def get_item_url(
         from_url: str | None = None,
         # YORE: Bump 2: Remove line.
         fallback: Callable[[str], Sequence[str]] | None = None,
-    ) -> str:
+    ) -> URLAndTitle:
         """Return a site-relative URL with anchor to the identifier, if it's present anywhere.
 
         Arguments:
@@ -252,11 +313,12 @@ def get_item_url(
         """
         # YORE: Bump 2: Replace `, fallback` with `` within line.
         url = self._get_item_url(identifier, from_url, fallback)
+        title = self._title_map.get(url) or None
         if from_url is not None:
             parsed = urlsplit(url)
             if not parsed.scheme and not parsed.netloc:
-                return relative_url(from_url, url)
-        return url
+                url = relative_url(from_url, url)
+        return url, title
 
     def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
         """Instantiate our Markdown extension.
@@ -287,7 +349,7 @@ def on_page_markdown(self, markdown: str, page: Page, **kwargs: Any) -> str:  #
             The same Markdown. We only use this hook to keep a reference to the current page URL,
                 used during Markdown conversion by the anchor scanner tree processor.
         """
-        self.current_page = page.url
+        self.current_page = page
         return markdown
 
     def on_page_content(self, html: str, page: Page, **kwargs: Any) -> str:  # noqa: ARG002
@@ -306,13 +368,15 @@ def on_page_content(self, html: str, page: Page, **kwargs: Any) -> str:  # noqa:
         Returns:
             The same HTML. We only use this hook to map anchors to URLs.
         """
+        self.current_page = page
+        # Collect `std`-domain URLs.
         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(page.url, item)
+                self.map_urls(item)
         return html
 
-    def map_urls(self, base_url: str, anchor: AnchorLink) -> None:
+    def map_urls(self, 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.
@@ -321,9 +385,32 @@ def map_urls(self, base_url: str, anchor: AnchorLink) -> None:
             base_url: The base URL to use as a prefix for each anchor's relative URL.
             anchor: The anchor to process and to recurse on.
         """
-        self.register_anchor(base_url, anchor.id, primary=True)
+        self.register_anchor(anchor.id, title=anchor.title, primary=True)
         for child in anchor.children:
-            self.map_urls(base_url, child)
+            self.map_urls(child)
+
+    def on_env(self, env:  Environment, /, *, config: MkDocsConfig, files: Files) -> Environment:
+        """Collect backlinks.
+
+        Hook for the [`on_env` event](https://www.mkdocs.org/user-guide/plugins/#on_env).
+        In this hook, we collect backlinks on every page. We do this now instead of in the `on_page_content` hook
+        so that all anchors have been registered, and so we can use them to discard useless backlinks.
+
+        Arguments:
+            env: The MkDocs environment.
+            config: The MkDocs config object.
+            files: The list of files in the MkDocs project.
+            kwargs: Additional arguments passed by MkDocs.
+
+        Returns:
+            The modified environment.
+        """
+        for file in files:
+            if file.page and file.page.content:
+                log.debug("Recording backlinks for page %s", file.page.file.src_path)
+                for identifier, backlink_type, backlink_anchor in _find_backlinks(file.page.content):
+                    self._record_backlink(identifier, backlink_type, f"{file.page.url}#{backlink_anchor}")
+        return env
 
     def on_post_page(self, output: str, page: Page, **kwargs: Any) -> str:  # noqa: ARG002
         """Fix cross-references.
@@ -348,6 +435,10 @@ def on_post_page(self, output: str, page: Page, **kwargs: Any) -> str:  # noqa:
         """
         log.debug("Fixing references in page %s", page.file.src_path)
 
+        self.current_page = page
+        # TODO: We could get rid of `from_url` parameters and use `self.current_page` instead.
+        # Then we could just make `fix_refs` a method of this class.
+
         # YORE: Bump 2: Replace `, fallback=self.get_fallback_anchor` with `` within line.
         url_mapper = functools.partial(self.get_item_url, from_url=page.url, fallback=self.get_fallback_anchor)
         # YORE: Bump 2: Replace `, _legacy_refs=self.legacy_refs` with `` within line.