Rename get_anchor method before removal in mkdocstrings

[pawamoy]

There wasn't any deprecation warning, my bad.

It's also possible to return a tuple instead of a set.

[oprypin]

Thanks.

Hm probably a tuple will be more performant.

And it's actually really interesting - the order of the identifiers actually matters because they get iterated sequentially.
I also took care to define it as Sequence[str] in autorefs, but in mkdocstrings-python for some reason it is now tuple | set (of which set doesn't even satisfy Sequence).
https://github.com/search?q=org%3Amkdocstrings+get_anchors&type=code
https://github.com/mkdocstrings/autorefs/blob/a92e88458f19c188211e38e80d798e4c14173539/src/mkdocs_autorefs/plugin.py#L87

also also I just noticed this new commit:
mkdocstrings/mkdocstrings@ee93e80#diff-09d6e30b41d735c060b7d3f13d324a2764dcb90502715c706bdb6aaca6393081R142
sorted is also kind of an arbitrary order? Why don't we just keep it the original order as it gets provided by the list of fallback anchors?

[pawamoy]

Thanks for the thorough checkup. I needed to deduplicate ids in the Python handler, that's probably why I wanted it to accept sets, but I did it in a half-assed way.

About the order being important, I think it is for autorefs indeed, but not as much for inventories.

• when falling back on additional ids to find a cross-ref, using sets gives nondeterministic results if a same object is rendered in different places (which is the case in Griffe for example, I've yet to find an elegant way to prevent/deal with that). With tuples instead, results are deterministic but still not obviously correct. We're missing the intent of the developer here, to know which one of several locations should be preferred. Add priority option autorefs#25 would come in handy here, probably.
• regarding the change with sorted, the order of ids does not matter, however the order in which the same objects are rendered into different pages does. I used sorted simply to have entries in the objects.inv a bit more ordered (dicts keep ordering). But I realize now that registering all identifiers to the first location only is not correct either, since one id could be rendered in location A and one of its alias in location B. So once again we're missing the intent of the dev here: what's the public/preferred location? If we know that, we can postpone registering all remaining ids to this public location.

I'd like to put emphasis on the fact that these issues only arise when single objects get rendered into multiple locations. We can either fix them, or somehow recommend not doing that and document these limitations, maybe even providing ways to prevent multi-rendering.

[pawamoy]

OK, I've updated mkdocstrings, mkdocstrings-python, mkdocstrings-python-legacy, and mkdocstrings-crystal (this PR) to always return tuples of strings, not sets.

Now, the priority issue for autorefs can be handled later, and I'd like to tackle the inventory issue in all handlers at once, in mkdocstrings. Rougly, in mkdocstrings extension:

if "data-role" in heading.attrib:
    self._handlers.inventory.register(
        name=rendered_anchor,
        domain=handler.domain,
        role=heading.attrib["data-role"],
        uri=f"{page}#{rendered_anchor}",
        # always overwrite for the heading that was just rendered
        overwrite=True,
    )
    for anchor in handler.get_anchors(data):
        self._handlers.inventory.register(
            name=anchor,
            domain=handler.domain,
            role=heading.attrib["data-role"],
            uri=f"{page}#{rendered_anchor}",
            # do not overwrite by default, only when user specified this location
            # to be the preferred one (through a handler option, to be determined)
            overwrite=heading.attrib.get("data-preferred-location", False)

If we want to ensure the inventory doesn't change across runs, we can sort it when writing it to disk. No need to do it earlier.

[pawamoy]

If you prefer, I can add back get_anchor to mkdocstrings with a deprecation warning, to give you more time 🙂

[oprypin]

Thanks

[oprypin]

This is now released