New features of autodoc in Sphinx-2.4

Today, I released Sphinx-2.4.0, now available on the Python package index at https://pypi.org/project/Sphinx/. It includes 18 new features and 23 bugfixes.

For the full changelog, go to http://www.sphinx-doc.org/en/master/changes.html.

In this article, I'd like to introduce you to new features of autodoc.

Support type annotations for variables

Until now, autodoc did not document type annotations for variables even if annotated in source code. But, since 2.4, it goes to document now. Nowadays, it becomes important to annotate type hints to make large programs. With this change, type hints help not only you and your team, but also the reader of document for your library or framework.

In addition, autodoc start to supports type annotated variables without initial value (declared in PEP-526). For example, Starship.captain and Starship.damage will be documented as instance variable with type annotation from following code since 2.4.

class Starship:
    captain: str
    damage: int

This change also supports dataclasses (since Python 3.7) to be documented.

Support type comment styled type annotation

Autodoc also starts to support type comment styled type annotation (ex. # type: (str) -> str). It is usually used before appearance of type-annotation syntax. And it migh used in long living project. I hope this helps them.

Note: typed_ast package is needed additionally if you use python3.7 or older.

Show type annotations as its description (experimental)

We added a new extension sphinx.ext.autodoc.typehints as an experimental feature. It extends existing feature autodoc_typehints and it allows to show type annotations as its description.

You can use it via loading the extension and set autodoc_typehints = "description" in your conf.py.

To learn it, let's see how autodoc_typehints works. It switches the representation of type annotations. Now it has 3 modes; signature, none and description (new!).

I made a simple function for example. Let's see these modes works.

def hello(name: str, age: int) -> str:
    """Hello world!

    :param name: Your name
    :param age: Your age
    :returns: greeting message
    """

signature mode

The signature mode shows type annotations in the signature of functions as is. It is default settings of autodoc_typehints. f:id:tk0miya:20200209184759p:plain

It is same as python code. So it is easy to read for python programmers. But it sometimes goes to bad when target function is complex. For example, the document of tornado.httpclient.HTTPRequest is one of hardest document to read for humans. f:id:tk0miya:20200209185142p:plain

none mode

The none mode helps to document such complex functions. It suppress type annotations on the signature of functions. f:id:tk0miya:20200209185337p:plain

This makes document simple. But type hints are lost at same time. So you need to add description of parameters in your docstring manually. This mode has affinity with google-style or numpy-style docstring. Because these style usually describes type annotations obviously.

description mode (new!)

As a new comer, the description mode shows type annotations as description of function. They will be merged into info-field lists if written in docstring. f:id:tk0miya:20200209185913p:plain

Personally, I prefer this mode to create API docs. We marked this as an experimental feature. But it will be adopted to formal one if no big bugs found. Please try this in your project and report if you see some trouble.

Note: description mode is only available when sphinx.ext.autodoc.typehints extension is loaded manually.

p.s.

There are many new features and bug fixes. So please read CHANGES file. And please let us know if you see an unexpected behavior.

Enjoy documentation!

p.s.2

Please become my sponsor if you like Sphinx and my OSS products! My GitHub sponsors page is here: https://github.com/sponsors/tk0miya