'Could not find cross-reference target' for custom handler

[makkus]

Describe the bug

I've written a custom handler to auto-generate documentation for internal models within my app, I'm using this handler, in addition to the python legacy one to create API docs. The index pages are generated with mkdocs-gen-files, and those work fine, both the custom models as well as the Python doc displays as it should (albeit ugly, I haven't gotten around to making it prettier, but that's a different issue).

If I use cross-reference links within the actual markdown section of the documentation, the links to Python models work fine. But my custom ones don't. I'm getting errors like:

WARNING  -  mkdocs_autorefs.plugin: install.md: Could not find cross-reference target '[kiara_info.modules.value.hash]'

I added some debug output in both my collector and renderer, and I am fairly sure both do what they are supposed to do. Is there a good way to debug this? I have no idea where to start. It's also very possible that I'm using this wrong, and my custom handler is to blame. I'd still need a few pointers on where to begin looking, though.

Here is an example:

• a page with example links, one working (Python), one isn't (my custom handler): https://dharpa.org/kiara/latest/install/#python-package (at the bottom)
• the 'source' markdown page for this: https://github.com/DHARPA-Project/kiara/blob/develop/docs/install.md
• the page where the link target is rendered (successfully): https://dharpa.org/kiara/latest/modules/value/#valuehash -- that page is generated dynamically, but debug output shows me this string is rendered for this example:

### `value.hash`

::: kiara_info.modules.value.hash
    handler: kiara

• the code for the collector: https://github.com/DHARPA-Project/kiara/blob/develop/src/kiara/doc/mkdocstrings/collector.py#L45
• and the code for the renderer: https://github.com/DHARPA-Project/kiara/blob/develop/src/kiara/doc/mkdocstrings/renderer.py#L12 (ignore the dynamic dispatch here, that is not used)
• mkdocs.yml: https://github.com/DHARPA-Project/kiara/blob/develop/mkdocs.yml

Is there something obvious wrong with what I'm doing?

To Reproduce
Steps to reproduce the behavior:

I don't expect anyone to actually install my project to figure this out, but in case you want to because you think it's a genuine bug, there are install instructions on the readme: https://github.com/DHARPA-Project/kiara

After it's in a virtual env, a simple: make docs or make serve-docs should suffice to build the documentation.

Expected behavior

I'd like to see links to the item description when using an identifier for my custom handler

Information (please complete the following information):

• OS: Linux/Ubuntu 21.10

• mkdocstrings version:

➜ pip list | grep mkdocs
mkdocs                      1.2.3
mkdocs-autorefs             0.3.1
mkdocs-awesome-pages-plugin 2.7.0
mkdocs-gen-files            0.3.4
mkdocs-literate-nav         0.4.1
mkdocs-macros-plugin        0.5.12
mkdocs-material             8.2.1
mkdocs-material-extensions  1.0.3
mkdocs-section-index        0.3.3
mkdocstrings                0.18.0
mkdocstrings-python-legacy  0.2.2

➜ python --version
Python 3.8.12

[pawamoy]

Nice work! I think your collector and renderer just lack one or two things.

First, the permalink of your hash objects is #valuehash. This is a good indication that autorefs, the plugin responsible for resolving cross-references, won't be able to find it using the full path kiara_info.modules.value.hash.

Second, and it's a bit hard to understand because lots of things happen in the code between mkdocstrings itself, autorefs, and the handlers: when autorefs cannot resolve a reference immediately, it falls back to asking every handler if it knows the reference, and if yes, what are its possible identifiers/anchors (in Python an object can have multiple identifiers, depending where it is defined and where it is imported and made public). It then iterates on these identifiers to see if it has knows a URL for it.

That's what I don't see in your renderer: the get_anchors method (example: https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/renderer.py#L130). Maybe your handler would have a way to return valuehash when kiara_info.modules.value.hash is passed? If not, I suggest to change the anchor/identifier your collector is building so that it uses the full path.

I hope this helps, let me know if something is unclear 🙂

[pawamoy]

Also, note that you can set a fallback_config class attribute on your collector to specify the configuration that must be used during fallback, instead of the default config.

From the PR that introduced it:

This change introduces a new attribute on collectors: fallback_config.
It is used by the Handlers.get_anchor method when collecting an object
to find its anchor. It allows to pass specific options to the collector
to avoid collecting the object members or, for example,
parsing Python docstrings, as it is not useful,
since we only care about the anchor.

See how I use it in the Python handler: https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/collector.py#L38 and https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/collector.py#L60

[makkus]

Thanks a lot for your help, I'll try that out tomorrow! I wasn't aware of the get_anchors method, it should be easy enough to wrangle the anchor/identifier in a way to make mkdocstrings happy.

[makkus]

Got it working, all it needed was me having to define a proper id for the anchor in my items list, and use that as result of the get_anchors method. I only return the one id, but I can see how this fallback mechanism can be very powerful. I'm sure I'll manage shoot myself in the foot with it once I try to do more fancy stuff, and end up here again :-)

Thanks again for your help, much appreciated!

[pawamoy]

You're very welcome 🙂