sphinx-autodoc-annotation
Use Python 3 annotations in sphinx-enabled docstrings
If you’re on Python 3 and writing sphinx-enabled docstrings, you might feel like doing needless work when typing :type arg: or :rtype: directives. After all, why not use annotations for this?
Sure, :param str arg: description is not a lot of work, but when you want to document your argument as a specific class for which you have a :class: link, then you need to use :type: and it’s cumbersome. By using this sphinx extension, you can turn this:
def f(a):
"""Do something.
:param a: description for a
:type a: :class:`ClassForA`
:rtype: str
"""
into:
def f(a: ClassForA) -> str:
"""Do something.
:param a: description for a
"""
Installation
First, you need Python 3.3+ and a Sphinx documentation (with autodoc enabled).
You can install sphinx-autodoc-annotation with:
$ pip install sphinx-autodoc-annotation
Then, you need to enable it in your conf.py file:
extensions = [
'sphinx.ext.autodoc',
'sphinx_autodoc_annotation',
]
You’re done!
Usage
All you need to do to use this extension is to properly annotate your functions and methods with expected types for your arguments and return value. :type: and :rtype: directives will automatically be added to your docstring.
These directives behave like if you added them manually, that is, your argument is not going to show up only with :type arg: you need :param arg: to be there (with a description of what it does) for your type to show up.
When there are no annotations, argument types are deduced from default values. If your default value is a bool, str, int or float, the argument is going to be considered of that type. That feature is there mainly because f(flag: bool = False) feels a bit redundant.
In all cases, :type: and :rtype: directives in the docstring will always have precedence over annotations and defaults.
2 maintainers
Metadata
2 maintainers
Release files for sphinx-autodoc-annotation 1.0-1
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 |
|---|---|---|---|---|
| sphinx-autodoc-annotation-1.0-1.tar.gz | 4.0 kB | Without provenance | Details for sphinx-autodoc-annotation-1.0-1.tar.gz |
Release files / sphinx-autodoc-annotation-1.0-1.tar.gz
| Download URL | sphinx-autodoc-annotation-1.0-1.tar.gz |
|---|---|
| Size | 4.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4a3d03081efe1e5f2bc9b9d00746550f45b9f543b0c79519c523168ca7f7d89a
|
|
BLAKE2b-256 checksum How to use checksums |
c92b81f620d831cd0632ba7583723ab42e840ba766b86868307ee0877c40a2e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Security for sphinx-autodoc-annotation 1.0-1
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.
