Move to mkdocstrings-python-xref

Author: ItsDrike

docs/contributing/guides/docstrings-and-reference.md

@@ -144,13 +144,22 @@ def foo():
     bar(custom_object)
 ```
 
-The references need to point to an object that is included in the docs (documented in API reference pages). **You will
-need to use the fully qualified name**. (You can't just use `[bar][bar]`, even if `bar` is defined in the same scope
-within the code. You will still need `[bar][mcproto.module_b.bar]`.) Sadly, while relative cross-references are
-supported, [mkdocstrings gates them for sponsors
+The references need to point to an object that is included in the docs (documented in API reference pages).
+
+### Relative Cross-References
+
+While relative cross-references are supported by mkdocstrings, they are [gated for sponsors
 only](https://mkdocstrings.github.io/python/usage/configuration/docstrings/#relative_crossrefs), at least until a
 funding goal is reached.
 
+For that reason, we're using an alternative handler to `mkdocstrings-python`:
+[`mkdocstrings-python-xref`](https://github.com/analog-garage/mkdocstrings-python-xref). This handler uses
+`mkdocstrings-python` internally, while extending it to provide support for relative cross-references. It is expected
+that once relative cross-refs come to mainline `mkdocstrings-python`, this alternative handler will be dropped.
+
+To use relative cross-references, check the [mkdocstrings-python-xref
+documentation](https://analog-garage.github.io/mkdocstrings-python-xref).
+
 ## Writing API Reference
 
 On top of just learning about how to write docstrings, you will need to understand how to write the docs for the API

mkdocs.yml

@@ -135,9 +135,9 @@ plugins:
       version_selector: true
   - mkdocstrings:
       enable_inventory: true
-      default_handler: python
+      default_handler: python_xref
       handlers:
-        python:
+        python_xref:
           options:
             docstring_options:
               ignore_init_summary: true

poetry.lock

@@ -67,8 +67,10 @@ mkdocs = "^1.6.0"
 mkdocs-material = "^9.5.30"
 mike = "^2.1.2"
 markdown-exec = { extras = ["ansi"], version = "^1.9.3" }
-towncrier = ">=23,<24.7"                                          # temporary pin, as 24.7 is incompatible with sphinxcontrib-towncrier
-mkdocstrings-python = { version = "^1.12.1", python = ">3.9,<4" }
+towncrier = ">=23,<24.7"                                  # temporary pin, as 24.7 is incompatible with sphinxcontrib-towncrier
+mkdocstrings = "0.27.0"
+mkdocstrings-python = "1.13.0"
+mkdocstrings-python-xref = "^1.6.2"
 
 [tool.poetry.group.docs-ci]
 optional = true