Документы Sphinx для составных типов данных

Question

Существует ли в Sphinx стандарт или наилучшая практика для предоставления более точных спецификаций для составных типов данных Python? Например, у меня есть функция, которая возвращает dict отображение str в str и использую numpydoc стиль. Должен ли я сделать что-то вроде:

Returns
-------
out : dict of str to str

или возможно dict of str: str?

Для списков, где тип контента известен, я заметил, что NumPy использует формат

foo : list of int

Есть ли стандарт или лучшая практика, которой следует следовать в этом общем случае?

Answer 1

Я не уверен, что это лучшая практика, но я обычно делаю что-то вроде :returns: dict( str=str ), Я думаю, что это действительно то, что лучше всего подходит для вас и вашего проекта. Если вы используете что-то вроде PyCharm, он порекомендует "лучший" вариант для ваших строк документации, но он постепенно перестанет рекомендовать что-то, так как он замечает, что вы делаете по-другому. Такие вещи, как PEP8, больше похожи на руководящие принципы (здесь я стараюсь произвести лучшее впечатление от Пиратов Карибского моря), а не на жесткие правила. Самое главное, можете ли вы это прочитать.

Один действительно хороший источник вдохновения - собственная документация Python. Если вы когда-нибудь просматриваете его и видите привлекательную страницу, посмотрите на левую боковую панель и нажмите " Показать исходный код", а затем просто скопируйте этот стиль... Я делаю это все время:)

Answer 2

Старый вопрос, но он по-прежнему был одним из самых популярных при поиске этой информации.

После дополнительных поисков я нашел это в документах Sphinx:

New in version 1.5.

Container types such as lists and dictionaries can be linked automatically using the 
following syntax:

:type priorities: list(int)  
:type priorities: list[int]
:type mapping: dict(str, int) 
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]