'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 :slightly_smiling_face:

[pawamoy]

Also, moving to discussion as this is more a support request than an actual issue.