Где ссылка на роли reStructuredText, необходимые для использования Sphinx и Sphinx autodo c, таких как Javado c?

Question

Я хотел бы использовать reStructuredText, Sphinx и Sphinx autodo c для Python кода таким же образом, как Javado c для Java кода, то есть для задания параметров и возвращаемых значений, но также для связи с другими классами, методами и т. д. c.

Мне очень трудно найти ссылку для обучения, как это сделать. В документации Sphinx упоминаются :param и :return: в качестве простых примеров списков полей. Я нигде не могу найти подходящую ссылку для этих ролей (и, по-моему, похожих, таких как «см. Также»).

Что еще более важно, мне неясно, как создавать ссылки для других классов и методов. особенно если они есть в других пакетах.

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

Обновление : обратите внимание, что я не имею в виду autodo c reference, На этой странице объясняется, как импортировать строки документов в произвольные документы Sphinx. Он не объясняет, какие роли можно использовать в строках документов для документирования параметров, возвращаемых значений, типов или для ссылки на другие методы и классы. Например, поиск на этой странице для :param ничего не находит.

Answer 1

Поля ReST, такие как param и return, которые можно использовать в строках документов, описаны в разделе «Списки информационных полей» в разделе «Python домен»: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info -field-lists .

Здесь описаны роли, доступные для создания перекрестных ссылок на документированные Python объекты: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross -referencing- python -объекты .

Вам также следует взглянуть на расширение Наполеона, которое поддерживает стили строк документации, которые многие люди находят более разборчивыми: https://sphinx-doc.org/en/master/usage/extensions/napoleon.html.