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

Question

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

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:

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

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

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

Мои расширения сфинкса:

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

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

Answer 1

Я не думаю, что вы можете поместить раздел атрибутов внутри своей строки документации, чтобы получить желаемые результаты.

Я попытался дать каждому атрибуту комментарий документа и указал тип и желаемый комментарий.

      class DataHolder:
"""
Class to hold some data

Each attribute needs its own doc comment with its type
"""

#: bool: Run without Gui
batch = False

#: bool: Show debug messages
debug = False

#: str: Object Name
name = 'default'

#: int: Object Version
version = 0

Это дает следующий результат и хорошее описание типа каждого вывода.

Взгляните сюда:

Answer 2

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

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

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

$ pydoc <modulename>

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

Answer 3

      class DataHolder:
    """
    Class to hold some data

    Attributes:
        batch: Run without GUI
        debug (bool): Show debug messages
        name: Object name
        int: Object version
    """
    batch: bool = False
    debug: bool = False
    name: str = 'default'
    version: int = 0
    # INLINE COMMENT for ONE line
    """
    DocString as inline-comment I havent seen that yet.
    """

Answer 4

      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"""