Skip to main content

An extension to Sphinx :code:`autodoc` to augment Sphinx documentation with type annotations, when using Python 2 style type annotations.

Project description

An extension to Sphinx autodoc to augment Sphinx documentation with type annotations, when using Python 2 style type annotations.

The Problem

Python 2 doesn’t support type annotations. Thus writing Python 2 / Python 3 agnostic code with type annotations requires putting the type annotations in comments:

def add(x, y):
    # type: (int, int) -> int
    """Adds two numbers."""
    return x + y

But now when documentation is generated with Sphinx, the documentation doesn’t include type annotations:

https://raw.githubusercontent.com/patrick-kidger/py2annotate/master/imgs/without-annotations.png

Example from the Signatory project.

The Solution

This extension remedies things so that the Sphinx documentation now looks like:

https://raw.githubusercontent.com/patrick-kidger/py2annotate/master/imgs/with-annotations.png

(which is the same as what you’d get using Python 3 style type annotations e.g. def add(x: int, y: int) -> int)

Installation

Via pip:

pip install py2annotate

It’s also just a single file, so copy-paste the code if you want.

Requires Python 3.6+.

Usage

Just add py2annotate to the list of extensions in conf.py:

# conf.py
...
extensions = ['sphinx.ext.autodoc', 'py2annotate']
...

(It shouldn’t matter whether it comes before or after autodoc.)

Note that Sphinx itself must be run using Python 3.6+. This is because py2annotate uses the Python 3 style type annotations internally in order to determine the correct annotations.

Known Issues

None so far! File a report if you run into anything. mypy and stubgen are used internally though, so your code’s formatting must be in a manner that they understand.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

py2annotate-1.1.1-py3-none-any.whl (4.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page