Simpler linking from doc pages to API reference page

[pchalasani]

We need the ability to link from a doc page in say docs/intro.md to an API doc page or sub-page (e.g. the "anchor" link to a class definition in the API page). For example in the Pydantic docs here: https://docs.pydantic.dev/latest/usage/models/

Currently we are having to provide the full path to the API doc page/anchor, e.g.

/reference/language_models/base/#langroid.language_models.base.LLMMessage

which is not fun to do. In the Pydantic docs they manage to achieve the linkage using just the portion after the #.
We need to figure out what settings in mkdocs.yml and/or other places need to be adjusted to achieve this.
Note that we are using auto-generated API doc pages via the gen-files plugin, and docs/auto_docstring.py script.
Pydantic's source code has some other plugins like this https://github.com/pydantic/pydantic/blob/main/docs/plugins/griffe_doclinks.py
Maybe we can use these as well.

[pawamoy]

Have you seen the docs for cross-references? https://mkdocstrings.github.io/usage/#cross-references

You don't need custom code, you can cross-ref to any API object using this syntax: [SomeObject][pkg.module.SomeObject].

[pchalasani]

Thanks for pointing this out (I recognize you're the author of the excellent mkdocstrings package!). Yes indeed we did look at the docs, but the linking did not work. It may have something to do with the fact that we are auto-generating the docs pages using the gen-files in mkdocs.yml and auto_docstring.py script.