Миграция от Javadoc до документации Python
Таким образом, я стал несколько привыкшим к документации стиля Javadoc. Просматривая различные примеры кода Python, я нахожу, что на первый взгляд документация, кажется, пропускает большую информацию.
Польза: варьируйтесь редко делают Вы видите самоочевидные биты документации. Docstrings обычно является абзацем или меньшим количеством английской разметки, которая интегрируется вместо того, чтобы выделиться на отдельных строках.
Плохое: в сочетании с вводом утки Python я нахожу, что много функций неясны о параметрах, которые они ожидают. Нет никакого вывода подсказок типа (утиный вывод подсказок?) и часто времена было бы хорошо иметь некоторую идею, что параметр должен быть подобным списку, подобным строке, подобным потоку.
Конечно, Javadoc был разработан для языка низшего уровня без больших способностей к самоанализу Python, который мог бы составлять менее подробную философию документации.
Совет относительно стандартов документации Python и лучших практик?
1 ответ
Формат reStructuredText был разработан в ответ на потребность в документации Python, которую можно было бы встроить в строки документации, поэтому лучше всего изучите reST и отформатируйте свои строки документации в этом формате . Вы можете обнаружить, как и я, что затем вы переходите к форматированию почти любой документации в reST, но это побочный момент: -)
Для конкретной документации вашего кода Python, Система Sphinx - это набор расширений формата reST и система сборки для визуализации документов. Поскольку он был разработан для документирования самого Python, включая стандартную библиотеку, Sphinx допускает очень хорошо структурированную документацию исходного кода , включая, конечно, особенности сигнатур функций по вашему запросу. Он позволяет создавать исчерпывающий набор документации, как автоматически извлекаемый, так и написанный вручную, с использованием одной и той же системы форматирования.
Если вы только хотите, чтобы документация была сгенерирована из вашего исходного кода, то Epydoc извлечет документацию API из вашего исходного кода ; он также считывает форматирование текста в формате reST.