change: Consider removing fallback feature

[pawamoy]

Is your change request related to a problem? Please describe.

Two or three years ago, I committed this change into mkdocstrings: mkdocstrings/mkdocstrings@c7ac043.

fix: Don't preemptively register identifiers as anchors

Registering every identifier of a rendered object is wrong,
since only one of these identifiers actually appear on the page.
What it tried to achieve instead was to register every identifier
as pointing to the rendered anchor. But autorefs doesn't have
mechanisms to do that unambiguously, yet.

Turns out autorefs now has such a mechanism: its plugin's register_anchor method now accepts a third argument, anchor, in addition to identifier. This change in autorefs was brought to support Markdown anchors, a solution to create unique heading aliases and avoid undeterministic resolution of cross-references when their identifiers appear on several pages.

Thanks to this change, we can now register all the anchors of an object (its aliases) so that they point to the actually rendered anchor on the page. This change will be done in mkdocstrings' AutoDocProcessor._process_headings method:

for anchor in anchors:
    if anchor != rendered_anchor:
        self._autorefs.register_anchor(page, anchor, rendered_anchor)

With this change, the fallback mechanism becomes useless. Indeed, when we fallback, we simply ask the handler to provide the known anchors, and we try again with those. Since we will now register these anchors ahead of time, if an identifier isn't found, the fallback mechanism will not find it either.

All in all, if handlers provide all relevant anchors of a given object (through their get_anchors method), then we can be sure that we won't ever need to fallback. So we could actually remove this mechanism entirely. It was wrong anyway, since it would query all handlers for anchors, which could yield false-positives (identifier matching in another handler). This could be fixed since autoref HTML elements now carry a domain value, but there's no point in fixing it if we can remove it.

Describe the solution you'd like

Entirely remove the fallback mechanism. There will be a nice ripple effect in handlers too: they won't have to maintain a fallback_config attribute, and the associated logic in their collect method. The base handler can also be cleaned up, as well as the Handlers class.

Handlers previously handled "fallback collection" differently, because the fallback logic was also triggered by optional cross-references to external projects for which we don't have an inventory loaded. In these cases, we didn't want to try and load additional data from the disk, just to get anchors, since we knew for sure the corresponding objects would not be rendered in the docs anyway (and so we wouldn't be able to cross-ref them).

Without the fallback logic firing, we pretty much know that each object we try to collect when getting anchors for each heading rendered on a page is already collected (and possibly cached) or at least is not external, so we don't need any special value or parameter to do collect data conditionally.

Is there something fundamental I'm missing about languages other than Python, which would require that we keep the fallback mechanism? Based solely on the logic, I would say no: the fallback just means fetching aliases to try with them. If we already registered these aliases, no point in falling back again.

Describe alternatives you've considered

Fix the fallback mechanism to only query handlers of the relevant domain. I tried locally, it works, with just one deprecation message (signature of callables accepted by autorefs.get_fallback_anchor now accepting a second argument, the domain).

Additional context

We will first have to implement the changes mentioned above in mkdocstrings.

[pawamoy]

Code is marked for removal thanks to Yore comments, we can close.

[Ravencentric]

Hi! I recently encountered this deprecation warning (atleast I think this is it) but from the error message I cannot find what's wrong so I can't actually fix it.

Here's the action run where it first appeared, I would appreciate any guidance for updating my docs to get rid of the deprecation warning:
https://github.com/Ravencentric/nzb/actions/runs/13093034718/job/36531930395#step:5:10
and here's the repo with the docs located in /docs:
https://github.com/Ravencentric/nzb/tree/fcde6f5060b2200c8658723fb166874882d91a7f

[pawamoy]

Sorry for the warning! You can probably remove it thanks to PYTHONWARNINGS but note that it will disappear with the very next mkdocstrings version, which should be released in one or two days 🙂

[Ravencentric]

I didn't want to silence the warning, was just looking to fix it but if it's going to fix itself in a few days then I don't mind. Thank you!

[pawamoy]

I see, thanks. Yeah MkDocs displays all deprecation warnings, even when you don't have control over the portion of code that is triggering them. In general, if the warning does not originate from your own code, you can ignore it, hide it, or report it to the relevant project 🙂 In our case it was reported here as well: mkdocstrings/python#232.