Документация на Python (: obj: `str`) vs (str)

Я читал этот документ Example Google Style Python Docstrings, чтобы понять, как написана хорошая документация на Python. Но я ничего не могу понять.Документация на Python (: obj: `str`) vs (str)

При записи строк, это странное обозначение.

Например, при документировании аргументов, документация определяет их записать как:

Args: 
    arg1(str): The description for arg1

Но, в некоторых других местах, документ что-то вроде пишет:

Args: 
    param2 (:obj:`str`, optional): The second parameter.

Во втором случае, почему строка представлена как :obj:`str`, а не просто str? Почему два представления для strings в первую очередь? Когда я буду использовать что?

источник

2016-08-16 ironstein

Поскольку нет никакого стандарта. Второй вариант, по-видимому, использует [аннотации стиля сфинкса] (http://www.sphinx-doc.org). –

Я не уверен, что этот документ, который вы нашли, великолепно; а не когда это внутренне противоречиво. –

@MartijnPieters вы могли бы указать мне на лучший документ – ironstein

Я думаю, что ответ на ваш вопрос приведен в Python: Journey from Novice to Expert. По-видимому, если вы напишете :obj:str, ваша документация Sphinx будет содержать ссылку на объект str в стандартной документации Python.

Кстати, эти обозначения не ограничиваются строками. В строках документации в ExampleError класса в Example Google Style Python Docstrings он говорит:

Args: 
    msg (str): Human readable string describing the exception. 
    code (:obj:`int`, optional): Error code.

источник

2017-09-28 09:44:28 user1919235

Документация на Python (: obj: `str`) vs (str)

ответ

Смежные вопросы