Я использую sphinx и плагин autodoc для создания документации API для моих модулей Python. Хотя я вижу, как красиво документировать определенные параметры, я не могу найти пример того, как документировать **kwargs
параметр.
Есть ли у кого-нибудь хороший пример четкого способа их документировать?
Ответы:
Я думаю, что
subprocess
-module docs - хороший пример. Дайте исчерпывающий список всех параметров для верхнего / родительского класса . Тогда просто обратитесь к этому списку для всех остальных случаев**kwargs
.источник
subprocess.call(*popenargs, **kwargs)
. В документацииsubprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False)
указано, что все, что*
находится после символа, является распознанными ключами в**kwargs
(или, по крайней мере, теми, которые часто используются)subprocess.Popen
и я не уверен, что это сейчас особенно хороший пример.Найдя этот вопрос, я остановился на следующем, что является действительным Sphinx и работает довольно хорошо:
r"""..."""
Требуется , чтобы сделать это «сырой» и , таким образом , строка документации держать\*
нетронутыми (для Сфинкса , чтобы забрать в качестве литерала*
, а не в начале «упор»).Выбранное форматирование (маркированный список с типом в скобках и описанием, разделенным m-тире) просто соответствует автоматическому форматированию, предоставляемому Sphinx.
После того, как вы приложили усилия, чтобы раздел «Аргументы ключевого слова» выглядел как раздел «Параметры» по умолчанию, кажется, что может быть проще с самого начала развернуть свой собственный раздел параметров (согласно некоторым другим ответам) , но в качестве доказательства концепции это один из способов добиться красивого внешнего вида дополнительных,
**kwargs
если вы уже используете Sphinx.источник
Строки документации Google Style, проанализированные Sphinx
Отказ от ответственности: не проверено.
Из этого вырезанного примера строки документации sphinx ,
*args
и**kwargs
остаются нерасширенными :Для компактности я бы предложил следующее решение:
Обратите внимание,
Optional
что для**key
аргументов не требуется .В противном случае вы можете попытаться явно указать * аргументы под
Other Parameters
и**kwargs
подKeyword Args
(см. Проанализированные разделы ):источник
В их документации есть пример doctstring для Sphinx. В частности, они показывают следующее:
Хотя вы спрашивали о сфинксЯ бы также указал на Руководство по стилю Google Python . Их пример со строкой документации, кажется, подразумевает, что они не вызывают специально kwargs. (other_silly_variable = Нет)
У ABB есть вопрос о принятом ответе на ссылку на документацию по управлению подпроцессами. Если вы импортируете модуль, вы можете быстро увидеть строки документации модуля через inspect.getsource.
Пример из интерпретатора Python с использованием рекомендации Silent Ghost:
Конечно, вы также можете просмотреть документацию по модулю с помощью функции справки. Например справка (подпроцесс)
Я лично не являюсь поклонником строки документации подпроцесса для kwargs в качестве примера, но, как и в примере Google, он не перечисляет kwargs отдельно, как показано в примере документации Sphinx.
Я включаю этот ответ на вопрос ABB, потому что стоит отметить, что вы можете просмотреть исходный код любого модуля или документацию таким образом, чтобы получить идеи и вдохновение для комментирования вашего кода.
источник
other_silly_variable
это не аргумент Кваргса, а вполне нормальный.Если кто-то еще ищет допустимый синтаксис ... Вот пример строки документации. Я сделал это именно так, надеюсь, это полезно для вас, но я не могу утверждать, что он соответствует чему-то конкретному.
источник
Это зависит от стиля документации, который вы используете, но если вы используете стиль numpydoc , рекомендуется документировать
**kwargs
использованиеOther Parameters
.Например, следующий пример Куорниана:
Обратите особое внимание на то, что рекомендуется указать значения по умолчанию для kwargs, поскольку они не очевидны из сигнатуры функции.
источник
Если вы ищете, как это сделать в стиле numpydoc , вы можете просто указать
**kwargs
в разделе параметров без указания типа - как показано в примере numpydoc из наполеона расширения sphinx и руководства по строкам документации из спринта документации pandas 2018.Вот пример , который я нашел из LSST руководства разработчика , который очень хорошо объясняет то , что должно быть описание из
**kwargs
параметра:В качестве альтернативы, основываясь на том, что предложил @Jonas Adler, я считаю, что лучше поставить
**kwargs
и его описание вOther Parameters
раздел - даже этот пример из руководства документации matplotlib предполагает то же самое.источник