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 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.
This package extends mkdocstrings-python to support an improved cross-reference syntax, that allows you to write doc-strings with relative cross-references like:
class MyClass:
def this_method(self):
"""
See [other_method][..] from [MyClass][(c)]
"""
rather than:
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:
$ 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
Metadata
Release files for mkdocstrings-python-betterrefs 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mkdocstrings_python_betterrefs-1.0.2.tar.gz | 83.4 kB | With provenance | Details for mkdocstrings_python_betterrefs-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mkdocstrings_python_betterrefs-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for mkdocstrings_python_betterrefs-1.0.2-py3-none-any.whl |
Total release size: 98.6 kB
Release files / mkdocstrings_python_betterrefs-1.0.2.tar.gz
| Download URL | mkdocstrings_python_betterrefs-1.0.2.tar.gz |
|---|---|
| Size | 83.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
98f678de0953eb2ab381c10acb304672dc0ed33945ef04d6b76a72eaa9d6afae
|
|
BLAKE2b-256 checksum How to use checksums |
b37e5cb5643da3959944f59f5da49455754fea9de527178a796910450696c129
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 21, 2025.
Transparency logRelease files / mkdocstrings_python_betterrefs-1.0.2-py3-none-any.whl
| Download URL | mkdocstrings_python_betterrefs-1.0.2-py3-none-any.whl |
|---|---|
| Size | 15.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a8dd38cf83f01a717966a9edbad26605ac5528d8411d839caaead1c7ea1998a
|
|
BLAKE2b-256 checksum How to use checksums |
79eb7c7a21058b6dfb75a9dff10c1d59ad2083a4229b05ea95e48ec6f58c2fa3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 21, 2025.
Transparency logSecurity for mkdocstrings-python-betterrefs 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mkdocstrings_python_betterrefs-1.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 21, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.