Как документировать константу модуля в Python?

К сожалению, переменные (и константы) не имеют docstrings. В конце концов, переменная является всего лишь именем целого числа, и вы не захотите присоединить docstring к номеру 1 так, как вам хотелось бы, к функции или объекту класса.

Если вы посмотрите почти на любой модуль в stdlib, например pickle , вы увидите, что единственная документация, которую они используют, это комментарии. И да, это означает, что help(pickle) показывает только это:

 DATA APPEND = b'a' APPENDS = b'e' … 

… полностью игнорируя комментарии. Если вы хотите, чтобы ваши документы отображались во встроенной справке, вы должны добавить их в docstring модуля, что не совсем идеально.

Но Sphinx может делать больше, чем встроенная помощь. Вы можете настроить его для извлечения комментариев по константам или использовать autodata чтобы сделать это полуавтоматически. Например:

 #: Indicates some unknown error. API_ERROR = 1 

Несколько строк #: перед любой операцией присваивания или один комментарий справа от оператора, работают эффективно так же, как docstrings на объектах, захваченных автодоком. Который включает обработку встроенного rST и автоматическое создание заголовка rST для имени переменной; вам нечего делать, чтобы сделать эту работу.

В качестве побочного примечания вы можете захотеть использовать enum вместо отдельных констант, подобных этому. Если вы не используете Python 3.4 (которого вы, вероятно, еще не …), есть пакет backport.enum для flufl.enum или flufl.enum (который не идентичен, но он похож, поскольку это было основным вдохновением для модуля stdlib) для 2.6+.

В экземплярах Enum (а не flufl.enum , но версия stdlib / backport) могут даже быть docstrings:

 class MyErrors(enum.Enum): """Indicates some unknown error.""" API_ERROR = 1 """Indicates that the request was bad in some way.""" BAD_REQUEST = 2 """Indicates that the request is missing required parameters.""" MISSING_PARAMS = 3 

Хотя они, к сожалению, не отображаются в help(MyErrors.MISSING_PARAMS) , они являются документами, которые может получить Sphinx autodoc.

Вы можете использовать hash + colon для документирования атрибутов (класс или уровень модуля).

  #: Use this content as input for moo to do bar MY_CONSTANT = "foo" 

Это подхватит некоторые генераторы документов.

Пример здесь не смог найти лучшего свойства модуля документа Sphinx

Если вы поместите строку после переменной, то sphinx подберет ее как документацию переменной. Я знаю, что это работает, потому что я делаю это повсюду. Как это:

 FOO = 1 """ Constant signifying foo. Blah blah blah... """ # pylint: disable=W0105 

Директива pylint сообщает pylint о том, чтобы не помечать документацию как заявление без каких-либо последствий.

Это старый вопрос, но я отметил, что соответствующий ответ отсутствовал.

Или вы можете просто включить описание констант в docstring модуля через .. py: data :: . Таким образом, документация также доступна через интерактивную справку. Сфинкс сделает это красиво.

 """ Docstring for my module. .. data:: API_ERROR Indicates some unknown error. .. data:: BAD_REQUEST Indicates that the request was bad in some way. .. data:: MISSING_PARAMS Indicates that the request is missing required parameters. """ 

Я думаю, тебе здесь не повезло.

Python не поддерживает напрямую docstrings для переменных: нет атрибута, который может быть привязан к переменным и __doc__ интерактивном режиме, как атрибут __doc__ для модулей, классов и функций.

Источник .