feat: Add link_titles option and adapt related logic

This change adds a `link_titles` option that defaults to `"auto"`. In automatic mode, link titles are either:

- always set if Material for MkDocs and its instant preview feature aren't detected
- only set on external links otherwise (since instant preview are not supported on external links anyway)

The option also accepts the `True` and `False`, for always/never setting titles, respectively.

An update to the title logic accompanies this change in order to make use of recorded heading titles (a change brought two commit ago):

- optional cross-references will use the original title, and optionally append the identifier if it doesn't already appear in the title
- mandatory cross-references will use either the original title if there's one, or no title at all

This is because optional cross-refs are almost exclusively created by mkdocstrings handlers, and therefore displaying the identifier (full qualified name of objects) is useful when hovering on a link. Manual cross-references on the other hand can often be references to text sections, and should never display the section anchor. The limitation being that manual cross-references to API objects won't show the identifier. We could consider using an additional attribute (other than `optional`) to label cross-refs as "API objects" or not, though users would still have to annotate their manual cross-refs with such an attribute to enjoy the appended identifier to the title.

Issue-33: #33
Issue-62: #62

Author: pawamoy

README.md

@@ -182,3 +182,22 @@ You can also change the actual identifier of a heading, thanks again to the `att
 ```
 
 ...though note that this will impact the URL anchor too (and therefore the permalink to the heading).
+
+### Link titles
+
+When rendering cross-references, the autorefs plugin sets `title` HTML attributes on links. These titles are displayed as tooltips when hovering on links. For mandatory cross-references (user-written ones), the original title of the target section is used as tooltip, for example: `Original title`. For optional cross-references (typically rendered by mkdocstrings handlers), the identifier is appended to the original title, for example: `Original title (package.module.function)`. This is useful to indicate the fully qualified name of API objects.
+
+Since the presence of titles prevents [the instant preview feature of Material for MkDocs][instant-preview] from working, the autorefs plugin will detect when this theme and feature are used, and only set titles on *external* links (for which instant previews cannot work).
+
+If you want to force autorefs to always set titles, never set titles, or only set titles on external links, you can use the `link_titles` option:
+
+```yaml
+plugins:
+- autorefs:
+    link_titles: external
+    # link_titles: true
+    # link_titles: false
+    # link_titles: auto  # default
+```
+
+[instant-preview]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-previews

src/mkdocs_autorefs/plugin.py

@@ -13,12 +13,12 @@
 import functools
 import logging
 from pathlib import PurePosixPath as URL  # noqa: N814
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any, Callable, Literal
 from urllib.parse import urlsplit
 from warnings import warn
 
 from mkdocs.config.base import Config
-from mkdocs.config.config_options import Type
+from mkdocs.config.config_options import Choice, Type
 from mkdocs.plugins import BasePlugin, event_priority
 from mkdocs.structure.pages import Page
 
@@ -60,6 +60,22 @@ 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: bool | Literal["auto", "external"] = Choice((True, False, "auto", "external"), default="auto")  # type: ignore[assignment]
+    """Whether to set titles on links.
+
+    Such title attributes are displayed as tooltips when hovering over the links.
+
+    - `"auto"`: autorefs will detect whether the instant preview feature of Material for MkDocs is enabled,
+        and set titles on external links when it is, all links if it is not.
+    - `"external"`: autorefs will set titles on external links only.
+    - `True`: autorefs will set titles on all links.
+    - `False`: autorefs will not set any title attributes on links.
+
+    Titles are only set when they are different from the link's text.
+    Titles are constructed from the linked heading's original title,
+    optionally appending the identifier for API objects.
+    """
+
 
 class AutorefsPlugin(BasePlugin[AutorefsConfig]):
     """The `autorefs` plugin for `mkdocs`.
@@ -115,6 +131,8 @@ def __init__(self) -> None:
         # YORE: Bump 2: Remove line.
         self._get_fallback_anchor: Callable[[str], tuple[str, ...]] | None = None
 
+        self._link_titles: bool | Literal["external"] = True
+
     # YORE: Bump 2: Remove block.
     @property
     def get_fallback_anchor(self) -> Callable[[str], tuple[str, ...]] | None:
@@ -284,6 +302,18 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
         """
         log.debug("Adding AutorefsExtension to the list")
         config.markdown_extensions.append(AutorefsExtension(self))  # type: ignore[arg-type]
+
+        if self.config.link_titles == "auto":
+            if getattr(config.theme, "name", None) == "material" and "navigation.instant.preview" in config.theme.get(
+                "features",
+                (),
+            ):
+                self._link_titles = "external"
+            else:
+                self._link_titles = True
+        else:
+            self._link_titles = self.config.link_titles
+
         return config
 
     def on_page_markdown(self, markdown: str, page: Page, **kwargs: Any) -> str:  # noqa: ARG002
@@ -369,6 +399,7 @@ def on_env(self, env: Environment, /, *, config: MkDocsConfig, files: Files) ->
                 file.page.content, unmapped = fix_refs(
                     file.page.content,
                     url_mapper,
+                    link_titles=self._link_titles,
                     _legacy_refs=self.legacy_refs,
                 )
 

src/mkdocs_autorefs/references.py

@@ -10,7 +10,7 @@
 from functools import lru_cache
 from html import escape, unescape
 from html.parser import HTMLParser
-from typing import TYPE_CHECKING, Any, Callable, ClassVar
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal
 from urllib.parse import urlsplit
 from xml.etree.ElementTree import Element
 
@@ -319,7 +319,7 @@ class _AutorefsAttrs(dict):
     _handled_attrs: ClassVar[set[str]] = {
         "identifier",
         "optional",
-        "hover",
+        "hover",  # TODO: Remove at some point.
         "class",
         "domain",
         "role",
@@ -376,9 +376,22 @@ def _find_url(
     raise KeyError(f"None of the identifiers {identifiers} were found")
 
 
+def _tooltip(identifier: str, title: str | None) -> str:
+    if title:
+        # Don't append identifier if it's already in the title.
+        if identifier in title:
+            return title
+        # Append identifier (useful for API objects).
+        return f"{title} (<code>{identifier}</code>)"
+    # No title, just return the identifier.
+    return f"<code>{identifier}</code>"
+
+
 def fix_ref(
     url_mapper: Callable[[str], tuple[str, str | None]],
     unmapped: list[tuple[str, AutorefsHookInterface.Context | None]],
+    *,
+    link_titles: bool | Literal["external"] = True,
 ) -> Callable:
     """Return a `repl` function for [`re.sub`](https://docs.python.org/3/library/re.html#re.sub).
 
@@ -392,6 +405,7 @@ def fix_ref(
         url_mapper: A callable that gets an object's site URL by its identifier,
             such as [mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url][].
         unmapped: A list to store unmapped identifiers.
+        link_titles: How to set HTML titles on links. Always (`True`), never (`False`), or external-only (`"external"`).
 
     Returns:
         The actual function accepting a [`Match` object](https://docs.python.org/3/library/re.html#match-objects)
@@ -404,7 +418,6 @@ def inner(match: Match) -> str:
         identifier: str = attrs["identifier"]
         slug = attrs.get("slug", None)
         optional = "optional" in attrs
-        hover = "hover" in attrs
 
         identifiers = (identifier, slug) if slug else (identifier,)
 
@@ -413,9 +426,7 @@ def inner(match: Match) -> str:
         except KeyError:
             if optional:
                 log.debug("Unresolved optional cross-reference: %s", identifier)
-                if hover:
-                    return f'<span title="{identifier}">{title}</span>'
-                return title
+                return f'<span title="{identifier}">{title}</span>'
             unmapped.append((identifier, attrs.context))
             if title == identifier:
                 return f"[{identifier}][]"
@@ -425,36 +436,57 @@ def inner(match: Match) -> str:
 
         parsed = urlsplit(url)
         external = parsed.scheme or parsed.netloc
+
         classes = (attrs.get("class") or "").strip().split()
         classes = ["autorefs", "autorefs-external" if external else "autorefs-internal", *classes]
         class_attr = " ".join(classes)
+
         if remaining := attrs.remaining:
             remaining = f" {remaining}"
-        if optional and hover:
-            return f'<a class="{class_attr}" title="{identifier}" href="{escape(url)}"{remaining}>{title}</a>'
-        return f'<a class="{class_attr}" href="{escape(url)}"{remaining}>{title}</a>'
+
+        title_attr = ""
+        if link_titles is True or (link_titles == "external" and external):
+            if optional:
+                # The `optional` attribute is generally only added by mkdocstrings handlers,
+                # for API objects, meaning we can and should append the full identifier.
+                tooltip = _tooltip(identifier, original_title)
+            else:
+                # Autorefs without `optional` are generally user-written ones,
+                # so we should only use the original title.
+                tooltip = original_title or ""
+
+            if tooltip and tooltip not in f"<code>{title}</code>":
+                title_attr = f' title="{escape(tooltip)}"'
+
+        return f'<a class="{class_attr}"{title_attr} href="{escape(url)}"{remaining}>{title}</a>'
 
     return inner
 
 
 def fix_refs(
     html: str,
     url_mapper: Callable[[str], tuple[str, str | None]],
+    *,
+    link_titles: bool | Literal["external"] = 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.
 
     Arguments:
         html: The text to fix.
         url_mapper: A callable that gets an object's site URL by its identifier,
             such as [mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url][].
+        link_titles: How to set HTML titles on links. Always (`True`), never (`False`), or external-only (`"external"`).
 
     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), html)
+    html = AUTOREF_RE.sub(
+        fix_ref(url_mapper, unmapped, link_titles=link_titles),
+        html,
+    )
 
     # YORE: Bump 2: Remove block.
     if _legacy_refs:

tests/test_plugin.py

@@ -3,8 +3,11 @@
 from __future__ import annotations
 
 import functools
+from typing import Literal
 
 import pytest
+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
@@ -124,3 +127,51 @@ def test_use_closest_url(caplog: pytest.LogCaptureFixture, primary: bool) -> Non
     fix_refs('<autoref identifier="foo">Foo</autoref>', url_mapper, _legacy_refs=False)
     qualifier = "primary" if primary else "secondary"
     assert f"Multiple {qualifier} URLs found for 'foo': ['foo.html#foo', 'bar.html#foo']" not in caplog.text
+
+def test_on_config_hook() -> None:
+    """Check that the `on_config` hook runs without issue."""
+    plugin = AutorefsPlugin()
+    plugin.config = AutorefsConfig()
+    plugin.on_config(config=MkDocsConfig())
+
+
+def test_auto_link_titles_external() -> None:
+    """Check that `link_titles` are made external when automatic and Material is detected."""
+    plugin = AutorefsPlugin()
+    plugin.config = AutorefsConfig()
+    plugin.config.link_titles = "auto"
+    config = MkDocsConfig()
+    config.theme = Theme(name="material", features=["navigation.instant.preview"])
+    plugin.on_config(config=config)
+    assert plugin._link_titles == "external"
+
+
+def test_auto_link_titles() -> None:
+    """Check that `link_titles` are made true when automatic and Material is not detected."""
+    plugin = AutorefsPlugin()
+    plugin.config = AutorefsConfig()
+    plugin.config.link_titles = "auto"
+    config = MkDocsConfig()
+
+    config.theme = Theme(name="material", features=[])
+    plugin.on_config(config=config)
+    assert plugin._link_titles is True
+
+    config.theme = Theme("mkdocs")
+    plugin.on_config(config=config)
+    assert plugin._link_titles is True
+
+    config.theme = Theme("readthedocs")
+    plugin.on_config(config=config)
+    assert plugin._link_titles is True
+
+
+@pytest.mark.parametrize("link_titles", ["external", True, False])
+def test_explicit_link_titles(link_titles: bool | Literal["external"]) -> None:
+    """Check that explicit `link_titles` are kept unchanged."""
+    plugin = AutorefsPlugin()
+    plugin.config = AutorefsConfig()
+    plugin.config.link_titles = link_titles
+    plugin.on_config(config=MkDocsConfig())
+    assert plugin._link_titles is link_titles
+

tests/test_references.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from textwrap import dedent
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import markdown
 import pytest
@@ -46,12 +46,13 @@ def test_relative_url(current_url: str, to_url: str, href_url: str) -> None:
 
 
 def run_references_test(
-    url_map: dict[str, str],
+    url_map: Mapping[str, str],
     source: str,
     output: str,
     unmapped: list[tuple[str, AutorefsHookInterface.Context | None]] | None = None,
     from_url: str = "page.html",
-    extensions: Mapping = {},
+    extensions: Mapping[str, Mapping[str, Any]] | None = None,
+    title_map: Mapping[str, str] | None = None,
 ) -> None:
     """Help running tests about references.
 
@@ -62,11 +63,13 @@ def run_references_test(
         unmapped: The expected unmapped list.
         from_url: The source page URL.
     """
+    extensions = extensions or {}
     md = markdown.Markdown(extensions=[AutorefsExtension(), *extensions], extension_configs=extensions)
     content = md.convert(source)
+    title_map = title_map or {}
 
     def url_mapper(identifier: str) -> tuple[str, str | None]:
-        return relative_url(from_url, url_map[identifier]), None
+        return relative_url(from_url, url_map[identifier]), title_map.get(identifier, None)
 
     actual_output, actual_unmapped = fix_refs(content, url_mapper)
     assert actual_output == output
@@ -257,8 +260,8 @@ def test_custom_optional_reference() -> None:
     """Check that optional HTML-based references are expanded and never reported missing."""
     run_references_test(
         url_map={"ok": "ok.html#ok"},
-        source='<autoref optional identifier="bar">foo</autoref> <autoref identifier=ok optional>ok</autoref>',
-        output='<p>foo <a class="autorefs autorefs-internal" href="ok.html#ok">ok</a></p>',
+        source='<autoref optional identifier="foo">bar</autoref> <autoref optional identifier="ok">ok</autoref>',
+        output='<p><span title="foo">bar</span> <a class="autorefs autorefs-internal" href="ok.html#ok">ok</a></p>',
     )
 
 
@@ -273,15 +276,6 @@ def test_legacy_custom_optional_hover_reference() -> None:
         )
 
 
-def test_custom_optional_hover_reference() -> None:
-    """Check that optional-hover HTML-based references are expanded and never reported missing."""
-    run_references_test(
-        url_map={"ok": "ok.html#ok"},
-        source='<autoref optional hover identifier="bar">foo</autoref> <autoref optional identifier=ok hover>ok</autoref>',
-        output='<p><span title="bar">foo</span> <a class="autorefs autorefs-internal" title="ok" href="ok.html#ok">ok</a></p>',
-    )
-
-
 # YORE: Bump 2: Remove block.
 def test_legacy_external_references() -> None:
     """Check that external references are marked as such."""
@@ -405,8 +399,8 @@ def test_keep_data_attributes() -> None:
     """Keep HTML data attributes from autorefs spans."""
     run_references_test(
         url_map={"example": "https://e.com#a"},
-        source='<autoref optional identifier="example" class="hi ho" data-foo data-bar="0">e</autoref>',
-        output='<p><a class="autorefs autorefs-external hi ho" href="https://e.com#a" data-foo data-bar="0">e</a></p>',
+        source='<autoref optional identifier="example" class="hi ho" data-foo data-bar="0">example</autoref>',
+        output='<p><a class="autorefs autorefs-external hi ho" href="https://e.com#a" data-foo data-bar="0">example</a></p>',
     )
 
 
@@ -486,3 +480,22 @@ def test_no_fallback_for_provided_identifiers() -> None:
         output="<p>[Hello][Hello world]</p>",
         unmapped=[("Hello world", None)],
     )
+
+
+def test_title_use_identifier() -> None:
+    """Check that the identifier is used for the title."""
+    run_references_test(
+        url_map={"fully.qualified.name": "ok.html#fully.qualified.name"},
+        source='<autoref optional identifier="fully.qualified.name">name</autoref>',
+        output='<p><a class="autorefs autorefs-internal" title="fully.qualified.name" href="ok.html#fully.qualified.name">name</a></p>',
+    )
+
+
+def test_title_append_identifier() -> None:
+    """Check that the identifier is appended to the title."""
+    run_references_test(
+        url_map={"fully.qualified.name": "ok.html#fully.qualified.name"},
+        title_map={"fully.qualified.name": "Qualified Name"},
+        source='<autoref optional identifier="fully.qualified.name">name</autoref>',
+        output='<p><a class="autorefs autorefs-internal" title="Qualified Name (fully.qualified.name)" href="ok.html#fully.qualified.name">name</a></p>',
+    )