Таня Шлюссер - Автостопом по 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.