Как документировать константу модуля в Python?
У меня есть модуль errors.py
в котором определены несколько глобальных констант (примечание: я понимаю, что Python не имеет констант, но я определил их по соглашению с помощью UPPERCASE).
"""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
Используя reStructuredText, как я могу документировать эти константы? Как вы можете видеть, я перечислил docstring над ними, но я не нашел никакой документации, которая указывает на это, я только что сделал это как предположение.
- Как искать китайские и короткие слова в документации, созданной Sphinx?
- сфинкс тяжелый: неожиданный заголовок раздела – произвольные заголовки в функции docstring
- Как разместить маркированные списки в простых таблицах в реструктурированном тексте?
- Как добавить лишние пробелы между заголовком раздела и абзацем
- Документация Sphinx, ссылки на нумерованные фигуры
К сожалению, переменные (и константы) не имеют 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__
для модулей, классов и функций.
Источник .
- Fiddler не записывает запросы моего скрипта
- Получение индекса элемента при обработке списка с использованием карты в python
- Как бы я перекрестно ссылался на функцию, сгенерированную autodoc в Sphinx?
- «Неожиданное название раздела» с Sphinx – это проблема?
- Как веб-сайт Python создает свою онлайн-документацию?
- Python: Как я могу определить в sphinx, какие файлы .rst и каталоги должны использоваться?
- Есть ли поле doststring reST Python для уроков?
- Можно ли разместить разделы внутри контейнера в reStructuredText?
- Замены внутри ссылок в reST / Sphinx
- Многострочное описание описания параметра в docstring python
- Матричные латексные макросы в reStructuredText и Sphinx