Автостопом по Python - [34]
Файл INSTALL не особенно нужен в Python (но он может пригодиться для того, чтобы соответствовать требованиям лицензий вроде GPL). Инструкции по установке зачастую сокращаются до одной команды вроде pip install module или python setup.py install и добавляются в файл README.
Файл LICENSE должен присутствовать всегда и указывать лицензию, под которой ПО доступно общественности (см. раздел «Выбираем лицензию» далее в этой главе для получения более подробной информации.)
В файле TODO или одноименном разделе файла README должны быть представлены планы по развитию кода.
В файле CHANGELOG или одноименном разделе файла README должны быть приведены изменения, которые произошли с базой кода в последних версиях.
Публикация проекта
В зависимости от проекта ваша документация может содержать некоторые (или даже все) из этих компонентов:
• во введении должен даваться краткий обзор того, что можно сделать с продуктом (плюс один или два простых варианта использования). Этот раздел представляет собой 30-секундную речь, описывающую ваш проект;
• в разделе «Руководство» основные варианты использования описаны более подробно. Читатель пройдет пошаговую процедуру настройки рабочего прототипа;
• раздел API генерируется на основе кода (см. подраздел «Строки документации против блоковых комментариев» текущего раздела далее). В нем перечислены все доступные интерфейсы, параметры и возвращаемые значения;
• документация для разработчиков предназначена для тех, кто хочет внести свой вклад в проект. В ней могут содержаться соглашения, принятые в коде, и описываться общая стратегия проектирования.
Sphinx (http://sphinx.pocoo.org/) — самый популярный[49] инструмент для создания документации для Python. Используйте его: он преобразует язык разметки reStructured Text в огромное множество форматов, включая HTML, LaTeX (для печатаемых версий PDF), страницы руководства и простой текст.
Существует отличный бесплатный хостинг для вашей документации, созданной с помощью Sphinx: Read the Docs (http://readthedocs.org/). Используйте и его. Вы можете сконфигурировать его с помощью функций перехвата коммитов для вашего репозитория исходного кода, поэтому перестроение вашей документации будет происходить автоматически.
Sphinx знаменит благодаря генерации API. Он также хорошо работает для общей документации в проекте. Онлайн-версия книги «Автостопом по Python» создана с помощью Sphinx и размещена на сайте Read the Docs.
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).
Или начните вносить свой вклад в документацию к любимому проекту и учитесь в процессе чтения.
Строки документации против блоковых комментариев
Строки документации и блоки комментариев не взаимозаменяемы. Оба варианта могут применяться для функции или класса. Рассмотрим пример использования обоих.
Строки документации, размещенные в начале модуля или в начале файла __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).
Журналирование бывает двух видов:
• диагностическое журналирование — записываются все события, связанные с работой приложения. Если пользователь сообщает об ошибке, в этих журналах можно поискать контекст;
• ведение контрольных журналов — записываются события для бизнес-анализа. Транзакции пользователя (вроде истории посещений) могут быть извлечены и объединены с другой информацией о нем (вроде итоговых покупок) для отчетности или оптимизации бизнес-целей.
Единственный случай, когда print предпочтительнее журналирования, — если вам нужно отобразить справку для приложения командной строки. Рассмотрим причины, почему журналирование лучше, чем print:
