.. index:: pair: Sphinx ; 2.4.0 (2020-02-09) pair: Sphinx 2.4.0 ; autodoc pair: Sphinx ; Typing .. _sphinx_2_4_0: ========================================================================================= Sphinx **2.4.0 (2020-02-09) new features (typing) of sphinx.ext.autodoc in sphinx** ========================================================================================= .. seealso:: - https://github.com/sphinx-doc/sphinx/blob/master/CHANGES - https://github.com/sphinx-doc/sphinx/tree/v2.4.0 - https://github.com/sphinx-doc/sphinx/blob/v2.4.0/CHANGES - https://tk0miya.hatenablog.com/entry/2020/02/09/190523 - :ref:`sphinx_ext_autodoc` .. contents:: :depth: 3 New features of **sphinx.ext.autodoc** (typing) in sphinx 2.4.0 =================================================================== .. seealso:: - https://tk0miya.hatenablog.com/entry/2020/02/09/190523 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, :ref:`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. .. code-block:: python class Starship: captain: str damage: int This change also supports dataclasses (since Python 3.7) to be documented. .. _PEP-526: https://www.python.org/dev/peps/pep-0526/ Show **type annotations** as its description (experimental) ============================================================== .. seealso:: - :ref:`sphinx_ext_autodoc_typehints` We added a new extension ref:`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. .. code-block:: python def hello(name: str, age: int) -> str: """Hello world! :param name: Your name :param age: Your age :returns: greeting message """ .. _signature_mode: **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: **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: **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 :ref:`sphinx.ext.autodoc.typehints ` extension is loaded manually. New extension **sphinx.ext.autodoc.typehints** ================================================= .. seealso:: - :ref:`sphinx_ext_autodoc_typehints` Features added ================== .. seealso:: - :ref:`sphinx_ext_autodoc_typehints` * #6910: inheritance_diagram: Make the background of diagrams transparent * #6446: duration: Add ``sphinx.ext.durations`` to 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 :ref:`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.0 * SphinxTranslator 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: :rst:dir:`py:data` and :rst:dir:`py:attribute` take 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 ``-q`` option for quiet mode