Миграция с Javadoc на Python Документация

Question

Так что я немного привык к документации стиля Javadoc. Просматривая различные примеры кода Python, я нахожу, что сначала краснеть, документация кажется, чтобы не хватать большого количества информации.

Хорошее: редко меняются, вы видите самодостаточные биты документации. Докстоны обычно представляют собой абзац или менее английскую разметку, которая объединяется, а не выделяется на отдельные строки.

Плохо: в сочетании с утиной печатью Python я обнаружил, что многие функции неясно о параметрах, которые они ожидают. Нет никакого намека на тип (подсказка для утки?), И часто бывало, что было бы неплохо иметь представление о том, что параметр должен быть похожим на список, похожим на строки, похожим на поток.

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

Любые рекомендации по стандартам документации и лучшим практикам Python?

Answer 1

Формат reStructuredText был разработан в ответ на потребность в документации на Python, которые могут быть встроены в строках документации, так что лучше всего, чтобы узнать Rest и форматировать строки документации с этим форматом. Вы могли бы найти, как я сделал, что вы потом в формат только о любой документации в REST, но это точка на стороне :-)

Для специально документирования кода Python, система Sphinx представляет собой набор расширений в формате reST и системы сборки для рендеринга документов. Поскольку он был предназначен для документирования самого Python, включая стандартную библиотеку, Sphinx позволяет очень хорошо структурированную документацию по исходному коду, включая, конечно, специфику сигнатур функций, как вы просите. Он позволяет создавать комплексный набор документации, как автоматически извлеченный, так и написанный вручную, причем все они используют одну и ту же систему форматирования.

Если вы только хотят документация генерируется из исходного кода, то Epydoc извлечет документацию API из исходного кода; он также читает форматирование текста для текста.