# mkdocstrings-python-betterrefs
[](https://pypi.org/project/mkdocstrings-python-betterrefs/)
[](https://github.com/ItsDrike/mkdocstrings-python-betterrefs/blob/main/LICENSE.txt)
[](https://github.com/ItsDrike/mkdocstrings-python-betterrefs/actions/workflows/main.yml)
[](https://itsdrike.github.io/mkdocstrings-python-betterrefs)
Python handler for [mkdocstrings] with improved handling for cross-references, including relative ones.
[mkdocstrings] is an awesome plugin for [MkDocs] that can generate Markdown API documentation from comments in code. The
standard [python handler][mkdocstrings-python] allows you to create cross-reference links using the syntax
`[<title>][<path>]` where the path must either be the fully qualified name of the referent or is empty, in which case
the path is taken from the title.
[mkdocstrings-python] does already have support for cross-references, however, it is currently only available in the
insiders edition, which is limited to their sponsors. Additionally, this implementation is fairly limited in comparison
to what this project offers.
> [!TIP]
> For more information on the [mkdocstrings-python] official support of relative cross-references, check out the feature
> request proposing them: [here][official-xrefs-issue], and the docs detailing the configuration option:
> [here][official-xrefs-docs].
>
> It is expected that relative cross-references will make it into the open-source version once a funding goal of $2,000
> is reached. You can see the current progress towards this goal [here][official-xrefs-funding-goal].
This package extends [mkdocstrings-python] to support an improved cross-reference syntax, that allows you to write
doc-strings with relative cross-references like:
```python
class MyClass:
def this_method(self):
"""
See [other_method][..] from [MyClass][(c)]
"""
```
rather than:
```python
class MyClass:
def this_method(self):
"""
See [other_method][mypkg.mymod.MyClass.other_method]
from [MyClass][mypkg.mymod.Myclass]
"""
```
Relative references are especially useful for larger codebases with deeply nested package structure, where writing out
the absolute paths each time gets very burdensome.
Another benefit of this extension is that it will report source locations for bad references so that errors are easier
to find and fix. For example:
```bash
$ mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory: /home/jdoe/my-project/site
WARNING - mkdocstrings_handlers: file:///home/jdoe/my-project/src/myproj/bar.py:16:
Cannot load reference 'myproj.bar.bad'
```
For further details, please see the [Documentation](https://itsdrike.github.io/mkdocstrings-python-betterrefs)
[MkDocs]: https://mkdocs.readthedocs.io/
[mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings
[mkdocstrings-python]: https://github.com/mkdocstrings/python
[official-xrefs-issue]: https://github.com/mkdocstrings/python/issues/27
[official-xrefs-docs]: https://mkdocstrings.github.io/python/usage/configuration/docstrings/?h=relative#relative_crossrefs
[official-xrefs-funding-goal]: https://mkdocstrings.github.io/python/insiders/#funding
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocstrings-python-betterrefs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "ItsDrike <itsdrike@protonmail.com>",
"keywords": "documentation, mkdocstrings, mkdocstrings-handler",
"author": null,
"author_email": "Christopher Barber <Christopher.Barber@analog.com>, ItsDrike <itsdrike@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b3/7e/5cb5643da3959944f59f5da49455754fea9de527178a796910450696c129/mkdocstrings_python_betterrefs-1.0.2.tar.gz",
"platform": null,
"description": "# mkdocstrings-python-betterrefs\n\n\n[](https://pypi.org/project/mkdocstrings-python-betterrefs/)\n[](https://github.com/ItsDrike/mkdocstrings-python-betterrefs/blob/main/LICENSE.txt)\n[](https://github.com/ItsDrike/mkdocstrings-python-betterrefs/actions/workflows/main.yml)\n[](https://itsdrike.github.io/mkdocstrings-python-betterrefs)\n\nPython handler for [mkdocstrings] with improved handling for cross-references, including relative ones.\n\n[mkdocstrings] is an awesome plugin for [MkDocs] that can generate Markdown API documentation from comments in code. The\nstandard [python handler][mkdocstrings-python] allows you to create cross-reference links using the syntax\n`[<title>][<path>]` where the path must either be the fully qualified name of the referent or is empty, in which case\nthe path is taken from the title.\n\n[mkdocstrings-python] does already have support for cross-references, however, it is currently only available in the\ninsiders edition, which is limited to their sponsors. Additionally, this implementation is fairly limited in comparison\nto what this project offers.\n\n> [!TIP]\n> For more information on the [mkdocstrings-python] official support of relative cross-references, check out the feature\n> request proposing them: [here][official-xrefs-issue], and the docs detailing the configuration option:\n> [here][official-xrefs-docs].\n>\n> It is expected that relative cross-references will make it into the open-source version once a funding goal of $2,000\n> is reached. You can see the current progress towards this goal [here][official-xrefs-funding-goal].\n\nThis package extends [mkdocstrings-python] to support an improved cross-reference syntax, that allows you to write\ndoc-strings with relative cross-references like:\n\n```python\nclass MyClass:\n def this_method(self):\n \"\"\"\n See [other_method][..] from [MyClass][(c)]\n \"\"\"\n```\n\nrather than:\n\n```python\nclass MyClass:\n def this_method(self):\n \"\"\"\n See [other_method][mypkg.mymod.MyClass.other_method]\n from [MyClass][mypkg.mymod.Myclass]\n \"\"\"\n```\n\nRelative references are especially useful for larger codebases with deeply nested package structure, where writing out\nthe absolute paths each time gets very burdensome.\n\nAnother benefit of this extension is that it will report source locations for bad references so that errors are easier\nto find and fix. For example:\n\n```bash\n$ mkdocs build\nINFO - Cleaning site directory\nINFO - Building documentation to directory: /home/jdoe/my-project/site\nWARNING - mkdocstrings_handlers: file:///home/jdoe/my-project/src/myproj/bar.py:16:\n Cannot load reference 'myproj.bar.bad'\n```\n\nFor further details, please see the [Documentation](https://itsdrike.github.io/mkdocstrings-python-betterrefs)\n\n[MkDocs]: https://mkdocs.readthedocs.io/\n[mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings\n[mkdocstrings-python]: https://github.com/mkdocstrings/python\n[official-xrefs-issue]: https://github.com/mkdocstrings/python/issues/27\n[official-xrefs-docs]: https://mkdocstrings.github.io/python/usage/configuration/docstrings/?h=relative#relative_crossrefs\n[official-xrefs-funding-goal]: https://mkdocstrings.github.io/python/insiders/#funding\n",
"bugtrack_url": null,
"license": null,
"summary": "Extended mkdocstrings-python handler with better cross-references support",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://itsdrike.github.com/mkdocstrings-python-betterrefs/",
"Homepage": "https://itsdrike.github.com/mkdocstrings-python-betterrefs/",
"Issues": "https://github.com/ItsDrike/mkdocstrings-python-betterrefs/issues",
"Repository": "https://github.com/ItsDrike/mkdocstrings-python-betterrefs"
},
"split_keywords": [
"documentation",
" mkdocstrings",
" mkdocstrings-handler"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "79eb7c7a21058b6dfb75a9dff10c1d59ad2083a4229b05ea95e48ec6f58c2fa3",
"md5": "b628b7d14424f05266c137ac6103a683",
"sha256": "5a8dd38cf83f01a717966a9edbad26605ac5528d8411d839caaead1c7ea1998a"
},
"downloads": -1,
"filename": "mkdocstrings_python_betterrefs-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b628b7d14424f05266c137ac6103a683",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 15245,
"upload_time": "2025-02-21T01:55:37",
"upload_time_iso_8601": "2025-02-21T01:55:37.826411Z",
"url": "https://files.pythonhosted.org/packages/79/eb/7c7a21058b6dfb75a9dff10c1d59ad2083a4229b05ea95e48ec6f58c2fa3/mkdocstrings_python_betterrefs-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b37e5cb5643da3959944f59f5da49455754fea9de527178a796910450696c129",
"md5": "d516916a143db9990c23fa369cbb8802",
"sha256": "98f678de0953eb2ab381c10acb304672dc0ed33945ef04d6b76a72eaa9d6afae"
},
"downloads": -1,
"filename": "mkdocstrings_python_betterrefs-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "d516916a143db9990c23fa369cbb8802",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 83363,
"upload_time": "2025-02-21T01:55:39",
"upload_time_iso_8601": "2025-02-21T01:55:39.879066Z",
"url": "https://files.pythonhosted.org/packages/b3/7e/5cb5643da3959944f59f5da49455754fea9de527178a796910450696c129/mkdocstrings_python_betterrefs-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-21 01:55:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ItsDrike",
"github_project": "mkdocstrings-python-betterrefs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocstrings-python-betterrefs"
}
JSON
