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.
Raw data
{
"_id": null,
"home_page": "https://github.com/hsoft/sphinx-autodoc-annotation",
"name": "sphinx-autodoc-annotation",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Virgil Dupras; (Current maintainer: Nicolas Hainaux)",
"author_email": "nh.techn@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c9/2b/81f620d831cd0632ba7583723ab42e840ba766b86868307ee0877c40a2e2/sphinx-autodoc-annotation-1.0-1.tar.gz",
"platform": "UNKNOWN",
"description": "sphinx-autodoc-annotation\n=========================\n\n*Use Python 3 annotations in sphinx-enabled docstrings*\n\nIf you're on Python 3 and writing sphinx-enabled docstrings, you might feel like doing\nneedless work when typing ``:type arg:`` or ``:rtype:`` directives. After all, why not use\nannotations for this?\n\nSure, ``:param str arg: description`` is not a lot of work, but when you want to document your\nargument as a specific class for which you have a ``:class:`` link, then you need to use ``:type:``\nand it's cumbersome. By using this sphinx extension, you can turn this::\n\n def f(a):\n \"\"\"Do something.\n \n :param a: description for a\n :type a: :class:`ClassForA`\n :rtype: str\n \"\"\"\n\ninto::\n\n def f(a: ClassForA) -> str:\n \"\"\"Do something.\n \n :param a: description for a\n \"\"\"\n\nInstallation\n------------\n\nFirst, you need Python 3.3+ and a Sphinx documentation (with ``autodoc`` enabled).\n\nYou can install ``sphinx-autodoc-annotation`` with::\n\n $ pip install sphinx-autodoc-annotation\n\nThen, you need to enable it in your ``conf.py`` file::\n\n extensions = [\n 'sphinx.ext.autodoc',\n 'sphinx_autodoc_annotation',\n ]\n\nYou're done!\n\nUsage\n-----\n\nAll you need to do to use this extension is to properly annotate your functions and methods with\nexpected types for your arguments and return value. ``:type:`` and ``:rtype:`` directives will\nautomatically be added to your docstring.\n\nThese directives behave like if you added them manually, that is, your argument is not going to\nshow up only with ``:type arg:`` you *need* ``:param arg:`` to be there (with a description of what\nit does) for your type to show up.\n\nWhen there are no annotations, argument types are deduced from default values. If your default value\nis a ``bool``, ``str``, ``int`` or ``float``, the argument is going to be considered of that type.\nThat feature is there mainly because ``f(flag: bool = False)`` feels a bit redundant.\n\nIn all cases, ``:type:`` and ``:rtype:`` directives in the docstring will always have precedence\nover annotations and defaults.",
"bugtrack_url": null,
"license": "BSD",
"summary": "Use Python 3 annotations in sphinx-enabled docstrings",
"version": "1.0-1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "b0b85a1c7fcd171584a3b261256681d9",
"sha256": "4a3d03081efe1e5f2bc9b9d00746550f45b9f543b0c79519c523168ca7f7d89a"
},
"downloads": -1,
"filename": "sphinx-autodoc-annotation-1.0-1.tar.gz",
"has_sig": false,
"md5_digest": "b0b85a1c7fcd171584a3b261256681d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4049,
"upload_time": "2016-08-16T05:51:01",
"upload_time_iso_8601": "2016-08-16T05:51:01.493921Z",
"url": "https://files.pythonhosted.org/packages/c9/2b/81f620d831cd0632ba7583723ab42e840ba766b86868307ee0877c40a2e2/sphinx-autodoc-annotation-1.0-1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2016-08-16 05:51:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "hsoft",
"github_project": "sphinx-autodoc-annotation",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sphinx-autodoc-annotation"
}
JSON
