Документирование атрибутов класса с аннотациями типов

Я хочу автогенерировать документацию по моему коду из docstrings. У меня есть базовый класс, предназначенный для хранения некоторых данных:

class DataHolder:
    """
    Class to hold some data

    Attributes:
        batch: Run without GUI
        debug (bool): Show debug messages
    """
    batch: bool = False
    debug: bool = False
    name: str = 'default'
    """Object name"""
    version: int = 0
    """int: Object version"""

Мой rst файл:

DataHolder
==========

.. autoclass:: data_holder.DataHolder
   :members:

Я документировал каждый атрибут по-другому, чтобы показать разницу, вот результат:
enter image description here

Похоже, что Sphinx не может подключить раздел " Attributes " с реальными атрибутами, поэтому он не может отображать значение по умолчанию.

Конечным результатом, который я хотел бы достичь, является результат как для поля version с docstring, определенной как для batch. Я хочу отобразить имя атрибута со значением по умолчанию и типом, но взятым из аннотаций типа. Похоже, что Sphinx игнорирует аннотации типа в этом случае.

Мои расширения sphinx:

extensions = [
    'sphinx.ext.viewcode',
    'sphinx.ext.autodoc',
    'sphinxcontrib.napoleon',
]

Что я могу сделать для достижения такого поведения? Я не могу найти хороших примеров для такого варианта использования.

Ответ 1

Существует встроенная библиотека для генерации документов из doc_strings.

https://docs.python.org/2/library/pydoc.html

Все, что вам нужно, это выполнить

$ pydoc <modulename>

Он дает красивую документацию, перечисляющую doc_strings, определяет параметры и возвращаемые значения. Просто попробуйте.