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

Question

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

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

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

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

Какой-нибудь совет по стандартам документации и лучшим практикам Python?

Answer 1

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

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

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