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
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 | |
|---|---|---|---|
| sphinx-autodoc-annotation-1.0-1.tar.gz | 4.0 kB | Details |
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 |
