# mkdocstrings-python-xref
Python handler for [mkdocstrings] supporting relative cross-references.
[](https://pypi.org/project/mkdocstrings-python-xref/)
[](https://anaconda.org/conda-forge/whl2conda)
[](https://analog-garage.github.io/mkdocstrings-python-xref/)
[](https://github.com/analog-garage/mkdocstrings-python-xref/actions/workflows/main.yml)
[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. This works well when the names are short, but can be burdensome
in larger codebases with deeply nested package structures.
This package extends [mkdocstrings-python] to support a relative cross-reference syntax,
that allows you to write doc-strings with 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]
"""
```
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://analog-garage.github.io/mkdocstrings-python-xref/)
[MkDocs]: https://mkdocs.readthedocs.io/
[mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings
[mkdocstrings-python]: https://github.com/mkdocstrings/python
Raw data
{
"_id": null,
"home_page": "",
"name": "mkdocstrings-python-xref",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "documentation-tool,mkdocstrings,mkdocstrings-handler,python",
"author": "",
"author_email": "Christopher Barber <Christopher.Barber@analog.com>",
"download_url": "https://files.pythonhosted.org/packages/73/0c/92fe54325208198dfa1abf5aa77d76af963ede81a6313ed79f014d1b26e4/mkdocstrings_python_xref-1.6.0.1.tar.gz",
"platform": null,
"description": "# mkdocstrings-python-xref\n\nPython handler for [mkdocstrings] supporting relative cross-references.\n\n[](https://pypi.org/project/mkdocstrings-python-xref/)\n[](https://anaconda.org/conda-forge/whl2conda)\n[](https://analog-garage.github.io/mkdocstrings-python-xref/) \n\n \n[](https://github.com/analog-garage/mkdocstrings-python-xref/actions/workflows/main.yml)\n\n\n[mkdocstrings] is an awesome plugin for [MkDocs] that can generate Markdown API documentation\nfrom comments in code. The standard [python handler][mkdocstrings-python] allows you to\ncreate cross-reference links using the syntax `[<title>][<path>]` where the path must\neither be the fully qualified name of the referent or is empty, in which case the path\nis taken from the title. This works well when the names are short, but can be burdensome\nin larger codebases with deeply nested package structures.\n\nThis package extends [mkdocstrings-python] to support a relative cross-reference syntax,\nthat allows you to write doc-strings with cross-references like:\n\n```python\nclass MyClass:\n def this_method(self):\n \"\"\"\n See [other_method][..] from [MyClass][(c)]\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\nAnother benefit of this extension is that it will report source locations for bad references\nso that errors are easier to 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://analog-garage.github.io/mkdocstrings-python-xref/)\n\n[MkDocs]: https://mkdocs.readthedocs.io/\n[mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings\n[mkdocstrings-python]: https://github.com/mkdocstrings/python\n",
"bugtrack_url": null,
"license": "",
"summary": "Enhanced mkdocstrings python handler",
"version": "1.6.0.1",
"project_urls": {
"Documentation": "https://analog-garage.github.io/mkdocstrings-python-xref/",
"Repository": "https://github.com/analog-garage/mkdocstrings-python-xref"
},
"split_keywords": [
"documentation-tool",
"mkdocstrings",
"mkdocstrings-handler",
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "730c92fe54325208198dfa1abf5aa77d76af963ede81a6313ed79f014d1b26e4",
"md5": "447edb58c8a621f046c8edd2759ddfd5",
"sha256": "ce26e37c58d3c4fad16aece914f4eec1795f1970282a9c219682d3590fdc10a1"
},
"downloads": -1,
"filename": "mkdocstrings_python_xref-1.6.0.1.tar.gz",
"has_sig": false,
"md5_digest": "447edb58c8a621f046c8edd2759ddfd5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10899,
"upload_time": "2024-01-16T23:00:49",
"upload_time_iso_8601": "2024-01-16T23:00:49.708478Z",
"url": "https://files.pythonhosted.org/packages/73/0c/92fe54325208198dfa1abf5aa77d76af963ede81a6313ed79f014d1b26e4/mkdocstrings_python_xref-1.6.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-16 23:00:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "analog-garage",
"github_project": "mkdocstrings-python-xref",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocstrings-python-xref"
}
JSON
