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.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.
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 """
The signature mode shows type annotations in the signature of functions as is. It is default settings of autodoc_typehints.
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.
The none mode helps to document such complex functions. It suppress type annotations on the signature of functions.
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.
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.
There are many new features and bug fixes. So please read CHANGES file. And please let us know if you see an unexpected behavior.