mkdocs_autorefs ¤

def run(self, root: Element) -> None:
    """Run the tree processor.

    Arguments:
        root: The root element of the tree.
    """
    if self._plugin.current_page is not None:
        pending_anchors = _PendingAnchors(self._plugin)
        self._scan_anchors(root, pending_anchors)
        pending_anchors.flush()

def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802 (casing: parent method's name)
    """Register the extension.

    Add an instance of our [`AutorefsInlineProcessor`][mkdocs_autorefs.AutorefsInlineProcessor] to the Markdown parser.
    Also optionally add an instance of our [`AnchorScannerTreeProcessor`][mkdocs_autorefs.AnchorScannerTreeProcessor]
    and [`BacklinksTreeProcessor`][mkdocs_autorefs.BacklinksTreeProcessor] to the Markdown parser
    if a reference to the autorefs plugin was passed to this extension.

    Arguments:
        md: A `markdown.Markdown` instance.
    """
    md.inlinePatterns.register(
        AutorefsInlineProcessor(md),
        AutorefsInlineProcessor.name,
        priority=168,  # Right after markdown.inlinepatterns.ReferenceInlineProcessor
    )
    if self.plugin is not None:
        # Markdown anchors require the `attr_list` extension.
        if self.plugin.scan_toc and "attr_list" in md.treeprocessors:
            _log_enabling_markdown_anchors()
            md.treeprocessors.register(
                AnchorScannerTreeProcessor(self.plugin, md),
                AnchorScannerTreeProcessor.name,
                priority=0,
            )
        # Backlinks require IDs on headings, which are either set by `toc`,
        # or manually by the user with `attr_list`.
        if self.plugin.record_backlinks and ("attr_list" in md.treeprocessors or "toc" in md.treeprocessors):
            _log_enabling_backlinks()
            md.treeprocessors.register(
                BacklinksTreeProcessor(self.plugin, md),
                BacklinksTreeProcessor.name,
                priority=0,
            )

@abstractmethod
def expand_identifier(self, identifier: str) -> str:
    """Expand an identifier in a given context.

    Parameters:
        identifier: The identifier to expand.

    Returns:
        The expanded identifier.
    """
    raise NotImplementedError

@abstractmethod
def get_context(self) -> AutorefsHookInterface.Context:
    """Get the current context.

    Returns:
        The current context.
    """
    raise NotImplementedError

def handleMatch(self, m: Match[str], data: str) -> tuple[Element | None, int | None, int | None]:  # type: ignore[override]  # noqa: N802
    """Handle an element that matched.

    Arguments:
        m: The match object.
        data: The matched data.

    Returns:
        A new element or a tuple.
    """
    text, index, handled = self.getText(data, m.end(0))
    if not handled:
        return None, None, None

    identifier, slug, end, handled = self._eval_id(data, index, text)
    if not handled or identifier is None:
        return None, None, None

    if slug is None and re.search(r"[\x00-\x1f]", identifier):
        # Do nothing if the matched reference still contains control characters (from 0 to 31 included)
        # that weren't unstashed when trying to compute a slug of the title.
        return None, m.start(0), end

    return self._make_tag(identifier, text, slug=slug), m.start(0), end

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 set of backlinks as value.
        Each backlink is a tuple of (URL, title) tuples forming navigation breadcrumbs.
    """
    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].add(self._crumbs(from_url, backlink_url))
    return relative_backlinks

def get_item_url(
    self,
    identifier: str,
    from_url: str | None = None,
    # YORE: Bump 2: Remove line.
    fallback: Callable[[str], Sequence[str]] | None = None,
) -> tuple[str, str | None]:
    """Return a site-relative URL with anchor to the identifier, if it's present anywhere.

    Arguments:
        identifier: The anchor (without '#').
        from_url: The URL of the base page, from which we link towards the targeted pages.

    Returns:
        A site-relative 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:
            url = relative_url(from_url, url)
    return url, title

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.
    """
    # YORE: Bump 2: Remove block.
    if isinstance(page, str):
        try:
            page = self._url_to_page[page]
        except KeyError:
            page = self.current_page

    self.register_anchor(page, anchor.id, title=anchor.title, primary=True)
    for child in anchor.children:
        self.map_urls(page, child)

def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
    """Instantiate our Markdown extension.

    Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
    In this hook, we instantiate our [`AutorefsExtension`][mkdocs_autorefs.AutorefsExtension]
    and add it to the list of Markdown extensions used by `mkdocs`.

    Arguments:
        config: The MkDocs config object.

    Returns:
        The modified config.
    """
    _log.debug("Adding AutorefsExtension to the list")
    config.markdown_extensions.append(AutorefsExtension(self))  # type: ignore[arg-type]

    # YORE: Bump 2: Remove block.
    # mkdocstrings still uses the `page` attribute as a string.
    # Fortunately, it does so in f-strings, so we can simply patch the `__str__` method
    # to render the URL.
    Page.__str__ = lambda page: page.url  # type: ignore[method-assign,attr-defined]

    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

    if self.config.strip_title_tags == "auto":
        if getattr(config.theme, "name", None) == "material" and "content.tooltips" in config.theme.get(
            "features",
            (),
        ):
            self._strip_title_tags = False
        else:
            self._strip_title_tags = True
    else:
        self._strip_title_tags = self.config.strip_title_tags

    return config

@event_priority(-50)  # Late, after mkdocstrings has finished loading inventories.
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).
    In this hook, we try to fix unresolved references of the form `[title][identifier]` or `[identifier][]`.
    Doing that allows the user of `autorefs` to cross-reference objects in their documentation strings.
    It uses the native Markdown syntax so it's easy to remember and use.

    We log a warning for each reference that we couldn't map to an URL.

    We also collect backlinks at the same time. We fix cross-refs and collect backlinks in a single pass
    for performance reasons (we don't want to run the regular expression on each page twice).

    Arguments:
        env: The MkDocs environment.
        config: The MkDocs config object.
        files: The list of files in the MkDocs project.

    Returns:
        The unmodified environment.
    """
    for file in files:
        if file.page and file.page.content:
            _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,
            )
            backlink_recorder = (
                functools.partial(self._record_backlink, page_url=file.page.url) if self.record_backlinks else None
            )
            # 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,
                link_titles=self._link_titles,
                strip_title_tags=self._strip_title_tags,
                _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}'",
                    )

    return env

def on_page_content(self, html: str, page: Page, **kwargs: Any) -> str:  # noqa: ARG002
    """Map anchors to URLs.

    Hook for the [`on_page_content` event](https://www.mkdocs.org/user-guide/plugins/#on_page_content).
    In this hook, we map the IDs of every anchor found in the table of contents to the anchors absolute URLs.
    This mapping will be used later to fix unresolved reference of the form `[title][identifier]` or
    `[identifier][]`.

    Arguments:
        html: HTML converted from Markdown.
        page: The related MkDocs page instance.
        kwargs: Additional arguments passed by MkDocs.

    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, item)
    return html

def on_page_markdown(self, markdown: str, page: Page, **kwargs: Any) -> str:  # noqa: ARG002
    """Remember which page is the current one.

    Arguments:
        markdown: Input Markdown.
        page: The related MkDocs page instance.
        kwargs: Additional arguments passed by MkDocs.

    Returns:
        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.
    """
    # YORE: Bump 2: Remove line.
    self._url_to_page[page.url] = page
    self.current_page = page
    return markdown

def register_anchor(
    self,
    page: Page,
    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 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.
    """
    # YORE: Bump 2: Remove block.
    if isinstance(page, str):
        try:
            page = self._url_to_page[page]
        except KeyError:
            page = self.current_page

    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:
        if url not in url_map[identifier]:
            url_map[identifier].append(url)
    else:
        url_map[identifier] = [url]
    if title and url not in self._title_map:
        self._title_map[url] = title
    if self.record_backlinks and url not in self._backlink_page_map:
        self._backlink_page_map[url] = page

def register_url(self, identifier: str, url: str) -> None:
    """Register that the identifier should be turned into a link to this URL.

    Arguments:
        identifier: The new identifier.
        url: The absolute URL (including anchor, if needed) where this item can be found.
    """
    self._abs_url_map[identifier] = url

def run(self, root: Element) -> None:
    """Run the tree processor.

    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)