No project description provided
Project description
sphinx_autodoc_future_annotations
=================================
This extension allows you to use Python 3 type annotations for documenting module and class attributes and
function arguments and return types.
The extension also has support for cyclic imports needed due to type annotations.
The extension only works for Python 3.7 and higher and requires the use of ``from __future__ import annotations``.
Example:
.. code-block:: python
:caption: a_module.py
from __future__ import annotations
import typing as t
if t.TYPE_CHECKING:
import another_module
module_attribute: t.Optional[another_module.SomeClass] = None
'''An attribute of the module.'''
class AClass:
'''A class.'''
instance_attribute: int
'''An instance attribute.'''
class_attribute: float = 3.0
'''A class attribute.'''
def __init__(self, arg: t.Union[int, str]):
pass
def method(self) -> int:
'''A method.'''
pass
.. code-block:: python
:caption: another_module.py
from __future__ import annotations
import typing
if typing.TYPE_CHECKING:
import a_module
def function(arg: a_module.AClass):
'''A function.'''
pass
Installation and setup
----------------------
First, use pip to download and install the extension::
$ pip install sphinx_autodoc_future_annotations
Then, add the extension to your ``conf.py``:
.. code-block:: python
extensions = [
'sphinx.ext.autodoc',
'sphinx_autodoc_future_annotations',
]
How it works
------------
Cyclic imports needed due to type annotations are supported in the following way.
First, a hook is monkey-patched into ``sphinx.ext.autodoc`` to act when a module is imported.
This hook first imports the module normally.
Then it parses the module's code and finds any top-level ``if``\-statements that are conditional on
``TYPE_CHECKING`` from the ``typing`` module.
All statements inside such ``if``-statements are executed in the context of te module.
This makes the additional imports available to ``typing.get_type_hints``.
The extension listens to the ``autodoc-process-signature`` and ``autodoc-process-docstring``
Sphinx events. In the former, it strips the annotations from the function signature. In the latter,
it injects the appropriate ``:type argname:`` and ``:rtype:`` directives into the docstring.
The ``:type argname:`` and ``:rtype:`` directives are added if and only if no existing matching directive is found.
Empty ``:param argname:`` directives are added if no matching directive is found.
This allows to document the type of an argument without having to add trivial documentation on its use.
This extension does not currently have any configuration options.
Some of the code is adapted from `sphinx-autodoc-typehints`_.
.. _sphinx-autodoc-typehints: https://github.com/agronholm/sphinx-autodoc-typehints
Compatibility with sphinx.ext.napoleon
--------------------------------------
To use `sphinx.ext.napoleon`_ with sphinx_autodoc_future_annotations, make sure you load
`sphinx.ext.napoleon`_ first, **before** sphinx_autodoc_future_annotations.
.. _sphinx.ext.napoleon: http://www.sphinx-doc.org/en/stable/ext/napoleon.html
.. code-block:: python
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx_autodoc_future_annotations',
]
=================================
This extension allows you to use Python 3 type annotations for documenting module and class attributes and
function arguments and return types.
The extension also has support for cyclic imports needed due to type annotations.
The extension only works for Python 3.7 and higher and requires the use of ``from __future__ import annotations``.
Example:
.. code-block:: python
:caption: a_module.py
from __future__ import annotations
import typing as t
if t.TYPE_CHECKING:
import another_module
module_attribute: t.Optional[another_module.SomeClass] = None
'''An attribute of the module.'''
class AClass:
'''A class.'''
instance_attribute: int
'''An instance attribute.'''
class_attribute: float = 3.0
'''A class attribute.'''
def __init__(self, arg: t.Union[int, str]):
pass
def method(self) -> int:
'''A method.'''
pass
.. code-block:: python
:caption: another_module.py
from __future__ import annotations
import typing
if typing.TYPE_CHECKING:
import a_module
def function(arg: a_module.AClass):
'''A function.'''
pass
Installation and setup
----------------------
First, use pip to download and install the extension::
$ pip install sphinx_autodoc_future_annotations
Then, add the extension to your ``conf.py``:
.. code-block:: python
extensions = [
'sphinx.ext.autodoc',
'sphinx_autodoc_future_annotations',
]
How it works
------------
Cyclic imports needed due to type annotations are supported in the following way.
First, a hook is monkey-patched into ``sphinx.ext.autodoc`` to act when a module is imported.
This hook first imports the module normally.
Then it parses the module's code and finds any top-level ``if``\-statements that are conditional on
``TYPE_CHECKING`` from the ``typing`` module.
All statements inside such ``if``-statements are executed in the context of te module.
This makes the additional imports available to ``typing.get_type_hints``.
The extension listens to the ``autodoc-process-signature`` and ``autodoc-process-docstring``
Sphinx events. In the former, it strips the annotations from the function signature. In the latter,
it injects the appropriate ``:type argname:`` and ``:rtype:`` directives into the docstring.
The ``:type argname:`` and ``:rtype:`` directives are added if and only if no existing matching directive is found.
Empty ``:param argname:`` directives are added if no matching directive is found.
This allows to document the type of an argument without having to add trivial documentation on its use.
This extension does not currently have any configuration options.
Some of the code is adapted from `sphinx-autodoc-typehints`_.
.. _sphinx-autodoc-typehints: https://github.com/agronholm/sphinx-autodoc-typehints
Compatibility with sphinx.ext.napoleon
--------------------------------------
To use `sphinx.ext.napoleon`_ with sphinx_autodoc_future_annotations, make sure you load
`sphinx.ext.napoleon`_ first, **before** sphinx_autodoc_future_annotations.
.. _sphinx.ext.napoleon: http://www.sphinx-doc.org/en/stable/ext/napoleon.html
.. code-block:: python
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx_autodoc_future_annotations',
]
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for sphinx_autodoc_future_annotations-0.1.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8ef8f4aed36aedd5364afea88f213c24819e5ff0be27ed38fd0a982451a73dfc |
|
MD5 | c72de130af82c0d8a94939e4a5e22d8f |
|
BLAKE2b-256 | 970bf0970c690ed7f53f95e1b8fe535a962f986c738cfe8a02e9f99f4d3958c0 |
Close
Hashes for sphinx_autodoc_future_annotations-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d13871ef48c44ee355f775d01ad51ec971dd0b34209641e724cd1ead2ff560ac |
|
MD5 | 08e048c7eefa02f99fd16a0b4f04bf65 |
|
BLAKE2b-256 | 8d4eb85fa798b9e2486d43e6fc90605b4c335031997900350b163862443fd11c |