При использовании Sphinx, как я могу документировать элементы, у которых нет строк документации?

Question

Я пишу документацию для пакета, который я опубликовал, и я обнаружил, что чем тщательнее будет ваша документация, тем легче людям будет использовать ваш пакет (да) Я на самом деле очень весело с любовью пишу все функции и детали моего кода.

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

Я понимаю, что об использовании прямых строк документации не может быть и речи, потому что переменные не имеют строк документации, но, безусловно, Sphinx имеет какую-то функциональность вокруг этого? Иначе как люди будут документировать общедоступные значения, такие как константы?

Answer 1

Хотя это правда, Python переменные не могут иметь строки документации. Используя расширение Sphinx autodoc, директивы autodata и autoattribute позволяют документировать переменные и константы. Обратите внимание, что использование отличается в случае переменной уровня модуля или члена класса.

Кроме того, если вы хотите определить значение для члена в документации, отличное от значения programmati c, лучшим способом будет с использованием аннотаций .

autodata и autoattribute поддерживают опцию аннотации.

Sphinx может собирать комментарии к объявлениям переменных и включать их в документацию (хотя эти комментарии не являются строками документации, они будут отображаться в документации). ). Давайте рассмотрим минимальный рабочий пример:

Исходный файл your_module_name.py:

"""This modules documentation."""

ONE_CONSTANT = "A constant value."
"""Turns out the comment is rendered as a docstring if we put it underneath."""

#: Lets try it like this
TWO_CONSTANTS = 2000


class OneClass:
    """Commenting members of a class."""

    #: Lets try the third comment like this.
    THREE_CONSTANTS = 3000

    #: Lets try the forth comment like this.
    FOUR_CONSTANTS = 4000

Соответствующий your_module_name.rst:

your\_module\_name module
=========================

.. automodule:: your_module_name
   :members: ONE_CONSTANT, TWO_CONSTANTS

   .. autodata:: ONE_CONSTANT
      :annotation: =this annotation

   .. autoclass:: OneClass
      :members:
      :undoc-members:
      :show-inheritance:

Полученный HTML:

Последнее замечание: это может привести к адаптации некоторых соглашений, которые вы ранее использовали для комментирования переменных в исходном коде. Кроме того, если вы используете аннотации, вы не захотите включать этот элемент в autodata или automodule, чтобы избежать его включения дважды.