Я собираюсь начать проект, где я буду единственным, кто делает реальный код, и два менее опытных программиста (страшно думать о себе, как опытные!) будут наблюдать и делать предложения по программе в целом.
Есть ли хорошая (бесплатная) система, которую я могу использовать для предоставления документации для классов и функций на основе кода, который я написал? Скорее всего, это поможет им справиться со структурой данных.
Я использовал epydoc для создания документации для модулей Python из встроенных docstrings. Он довольно прост в использовании и генерирует приятный внешний вид в нескольких форматах.
python.org теперь использует sphinx для документации.
Мне лично нравится вывод сфинкса над epydoc. Я также чувствую, что реструктурированный текст легче читать в докстерах, чем разметка epydoc.
Sphinx может быть полезен для создания очень подробных и информативных документов, которые выходят за рамки того, что дает вам простой документ API. Однако во многих случаях вам лучше будет использовать вики для этих документов. Также рассмотрите возможность написания функциональных тестов, которые демонстрируют использование вашего кода, а не документацию на словах, как использовать ваш код.
Epydoc очень хорошо сканирует ваши документы и просматривает ваш код для создания документов API, но не обязательно хорош в предоставлении более подробная информация.
Существует достоинство наличия двух типов документации для проекта. Однако, если у вас есть временный хруст, всегда полезно иметь хорошее тестовое покрытие и значимые тесты, чем документацию.
Я использую Sphinx для своего проекта не только потому, что он выглядит хорошо, но также потому, что Sphinx рекомендует писать документацию для людей, чтобы читать, а не только компьютеры.
Я нахожу, что документация в стиле JavaDoc, созданная такими инструментами, как epydoc, довольно печатается. Слишком часто случается, что программист бездумно "документирует" аргументы и возвращает типы просто потому, что иначе в документах API будет недостаток. Таким образом, вы в конечном итоге получаете строку кода (которая должна выглядеть как Java, но прошло некоторое время с тех пор, как я написал Java, поэтому она не может компилироваться...)
/**
* Set the name.
*
* @param firstName the first name.
* @param lastName the last name.
*/
public void setName(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}
В этой так называемой "документации" имеется очень мало информации. Я предпочитаю путь Sphinx, где вы (используя плагин autodoc) просто пишете
.. autofunction:: set_name
и Sphinx добавит строку в вашу документацию, в которой будет указано
set_name(first_name,last_name)
и каждый программист на Python должен знать, что происходит.
См. ответы на can-i-document-python-code-with-doxygen-and-does-it-make-sense, особенно те, которые упоминаются Epydoc и pydoctor.