Таня Шлюссер - Автостопом по Python

Концепция BDD набрала популярность после того, как в 2011 году вышла книга 6e Cucumber Book (Pragmatic Bookshelf), где был задокументирован пакет Behave для Ruby. Это вдохновило Гэбриэла Фалько (Gabriel Falco) на создание Lettuce ( http://lettuce.it/), а Питера Паренте (Peter Parente) — на создание Behave ( http://pythonhosted.org/behave/) для нашего сообщества.

Поведения описываются простым текстом с помощью синтаксиса под названием Gherkin, который люди могут прочитать, а машины — понять. Вам могут пригодиться следующие руководства:

• руководство по Gherkin ( https://github.com/cucumber/cucumber/wiki/Gherkin);

• руководство по Lettuce ( http://lettuce.it/tutorial/simple.html);

• руководство по Behave ( http://tott-meetup.readthedocs.org/en/latest/sessions/behave.html).

Читаемость — главная цель разработчиков Python как в проектах, так и в документации. Приемы, описанные в этом разделе, помогут вам сэкономить немало времени.

Существует документация по API, предназначенная пользователям проектов, а также дополнительная документация для тех, кто хочет вносить в проект свой вклад. В этом разделе вы узнаете о дополнительной документации.

Файл README, расположенный в корневом каталоге, призван давать общую информацию как пользователям, так и тем, кто обслуживает проект. В нем должен быть либо простой текст, либо легкая для чтения разметка вроде reStructured Text (сейчас это единственный формат, который понимает PyPI [48] Для тех, кому интересно: развернулась дискуссия о введении поддержки ( https://bitbucket.org/pypa/pypi/issues/148/support-markdown-for-readmes ) в файлах README в PyPI. ) или Markdown ( https://help.github.com/articles/basic-writing-and-formatting-syntax/). Этот файл должен содержать несколько строк, описывающих предназначение проекта или библиотеки (предполагая, что пользователь ничего не знает о проекте), URL основного исходного кода ПО и информацию об авторах. Если вы планируете читать код, то в первую очередь должны ознакомиться с этим файлом.

Файл INSTALL не особенно нужен в Python (но он может пригодиться для того, чтобы соответствовать требованиям лицензий вроде GPL). Инструкции по установке зачастую сокращаются до одной команды вроде pip install module или python setup.py install и добавляются в файл README.

Файл LICENSE должен присутствовать всегда и указывать лицензию, под которой ПО доступно общественности (см. раздел «Выбираем лицензию» далее в этой главе для получения более подробной информации.)

В файле TODO или одноименном разделе файла README должны быть представлены планы по развитию кода.

В файле CHANGELOG или одноименном разделе файла README должны быть приведены изменения, которые произошли с базой кода в последних версиях.

В зависимости от проекта ваша документация может содержать некоторые (или даже все) из этих компонентов:

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

• в разделе «Руководство» основные варианты использования описаны более подробно. Читатель пройдет пошаговую процедуру настройки рабочего прототипа;

• раздел API генерируется на основе кода (см. подраздел «Строки документации против блоковых комментариев» текущего раздела далее). В нем перечислены все доступные интерфейсы, параметры и возвращаемые значения;

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

Sphinx ( http://sphinx.pocoo.org/) — самый популярный [49] Вы можете встретить и другие инструменты вроде Pycco, Ronn, Epydoc (больше не поддерживается) и MkDocs. Практически все используют Sphinx, мы также рекомендуем выбрать его. инструмент для создания документации для 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).

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

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

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

Строки документации описывают, как работает функция или класс, она будет показана в интерактивной сессии 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).

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

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