Разница между ":", "@" и ничем в строках документации python

Question

Я просто пытаюсь лучше понять расположение строк документации Python (Между """ """)

Я видел строки документации с различными макетами... такими как...

"""
@DESCRIPTION
Ive seen tags STARTING with an at-sign

:DESCRIPTION:
Tags with colons

DESCRIPTION
And tags with nothing

"""

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

Спасибо!

Answer 1

Форматы

Строки документации Python могут быть записаны в нескольких форматах:

- Javadoc

Исторически стиль javadoc был распространен. Он был использован Epydoc (с Epytext формат) для создания документации.

Пример:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- остальное

В настоящее время, вероятно, более распространенным форматом является формат reStructuredText (reST), который используется Sphinx для создания документации.

Пример:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

У Google есть свой собственный формат, который довольно часто используется. Это также может быть интерпретировано Сфинксом. Обратите внимание, что Numpy рекомендует следовать своим собственным numpydoc, основанным на формате Google и используемым Sphinx.

Пример:

"""
This is a groups style docs.

Parameters:
    param1 - this is the first param
    param2 - this is a second param

Returns:
    This is a description of what is returned

Raises:
    KeyError - raises an exception
"""

Преобразование / Генерация

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

Примечание. Примеры взяты из документации Pyment. Вы можете увидеть это Tuto для получения дополнительной информации о строках документации.

Answer 2

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

@ должен указать поля Epydoc.

Точка с запятой : в первую очередь для сфинкса (см. документацию по Сфинксу или ссылку выше).

Здесь есть соответствующий пост: что это за теги @ivar @param и @type в строке документации python?

Могут быть и другие варианты использования (возможно, в том числе Elixir, это не та технология, с которой я достаточно знаком, чтобы комментировать).

Надеюсь, это поможет.