Автостопом по Python

Существует отличный бесплатный хостинг для вашей документации, созданной с помощью Sphinx: Read the Docs (http://readthedocs.org/). Используйте и его. Вы можете сконфигурировать его с помощью функций перехвата коммитов для вашего репозитория исходного кода, поэтому перестроение вашей документации будет происходить автоматически.

Sphinx знаменит благодаря генерации API. Он также хорошо работает для общей документации в проекте. Онлайн-версия книги «Автостопом по Python» создана с помощью Sphinx и размещена на сайте Read the Docs.

reStructured Text

Sphinx использует формат reStructured Text (http://docutils.sourceforge.net/rst.html), с его помощью написана практически вся документация для Python. Если содержимое аргумента long_description функции setuptools.setup() написано в формате reStructured Text, оно будет отрисовано как HTML в PyPI — другие форматы будут представлены как простой текст. Он похож на Markdown, имеющий встроенные необязательные расширения. Следующие ресурсы подойдут для изучения синтаксиса:

• The reStructuredText Primer (http://sphinx.pocoo.org/rest.html);

• reStructuredText Quick Reference (http://bit.ly/restructured-text).

Или начните вносить свой вклад в документацию к любимому проекту и учитесь в процессе чтения.

Строки документации против блоковых комментариев

Строки документации и блоки комментариев не взаимозаменяемы. Оба варианта могут применяться для функции или класса. Рассмотрим пример использования обоих.

Первый блок комментария — это заметка для программиста.

Строки документации описывают, как работает функция или класс, она будет показана в интерактивной сессии Python, когда пользователь введет команду help(square_and_rooter).

Строки документации, размещенные в начале модуля или в начале файла __init__.py, также появятся в выводе функции help(). Функция autodoc для Sphinx может автоматически генерировать документацию с помощью правильно отформатированных строк. Инструкцию о том, как форматировать строки документации для autodoc, вы можете прочитать в руководстве к Sphinx (http://www.sphinx-doc.org/en/stable/tutorial.html#autodoc). Для получения более подробных сведений обратитесь к PEP 257 (https://www.python.org/dev/peps/pep-0257/).

Журналирование

Модуль журналирования был частью стандартной библиотеки Python, начиная с версии 2.3. Он кратко описан в PEP 282 (https://www.python.org/dev/peps/pep-0282/). Эту документацию сложно прочесть, исключение составляет простое руководство по журналированию (http://docs.python.org/howto/logging.html#logging-basic-tutorial).

Журналирование бывает двух видов:

• диагностическое журналирование — записываются все события, связанные с работой приложения. Если пользователь сообщает об ошибке, в этих журналах можно поискать контекст;

• ведение контрольных журналов — записываются события для бизнес-анализа. Транзакции пользователя (вроде истории посещений) могут быть извлечены и объединены с другой информацией о нем (вроде итоговых покупок) для отчетности или оптимизации бизнес-целей.