Sphinx 2.4.0 (2020-02-09) new features (typing) of sphinx.ext.autodoc in sphinx¶
See also
New features of sphinx.ext.autodoc (typing) in sphinx 2.4.0¶
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.
Show type annotations as its description (experimental)¶
We added a new extension ref:sphinx.ext.autodoc.typehints <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
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.
none mode¶
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.
Features added¶
#6910: inheritance_diagram: Make the background of diagrams transparent
#6446: duration: Add
sphinx.ext.durationsto inspect which documents slow down the build#6837: LaTeX: Support a nested table
#7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via environment variable
#6966: graphviz: Support
:class:option#6696: html:
:scale:option of image/figure directive not working for SVG images (imagesize-1.2.0 or above is required)#6994: imgconverter: Support illustrator file (.ai) to .png conversion
autodoc: Support Positional-Only Argument separator (PEP-570 compliant)
autodoc: Support type annotations for variables
#2755: autodoc: Add new event: autodoc-before-process-signature
#2755: autodoc: Support type_comment style (ex.
# type: (str) -> str) annotation (python3.8+ or typed_ast is required)#7051: autodoc: Support instance variables without defaults (PEP-526)
#6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints . It shows typehints as object description if
autodoc_typehints = "description"set. This is an experimental extension and it will be integrated into autodoc core in Sphinx-3.0SphinxTranslator now calls visitor/departure method for super node class if visitor/departure method for original node class not found
#6418: Add new event: object-description-transform
py domain:
py:dataandpy:attributetake new options named:type:and:value:to describe its type and initial value#6785: py domain:
:py:attr:is able to refer properties again#6772: apidoc: Add
-qoption for quiet mode