Рабочая документация в Sphinx

Существует несколько подходов к организации процесса программирования. Во всех подходах происходит попытка определения цели программного продукта. Посмотрим на выбор целей детально:

Техническое задание:

Классический «водопадный» подход. Сначала описывается объект автоматизации, его составляющие и функции. Также описываются требования, способы реализации и процедуры проверки. Подробнее можно посмотреть в ГОСТ-34 или западных аналогах, например RUP - Rational Unified Process (документ Use Case).

Плюсы

• в документ задания включены многие детали разработки.

Минусы

• разработка документа является фактически архитектурной работой, которая впоследствии сильно «отходит» от процесса разработки, появления новых интерфейсов

• планирование проекта опирается на локальные цели (недельный результат, конкретный модуль, пакет ошибок после тестрирования)

• проходит много времени, пока появится ощущение «правильности» разрабатываемого продукта, насколько удовлетворяются потребности предполагаемых потербителей

Ориентированная на тесты разработка:

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

Плюсы

• автоматизированное тестирование с полнотой проверки пользовательских сценариев

Минусы

• тестовые сценарии также быстро устаревают после нескольких итераций разработки и появления исправлений в пользовательских сценариях

• тесты понятны только программистам и нечетабельны для пользователей

Ориентированная на интерфейсы разработка:

Стремление включить пользователей в процесс разработки привело к появлению подхода прототипирования пользовательских интерфейсов. Графические изображения стали рисовать в разнообразных редакторах и пользователям предлагалось визуально оценить разрабатываемую программу.

Плюсы

• ранняя реакция пользователей на образ программы позволяет быстрее понять потребности пользователей и способы их реализации

Минусы

• пользователи в большинстве случаев не могут представить алгоритмическую последовательность представляемых им сценариев работы программы

• дизайнеры интерфейсов не глубоко разбираются в проектных задачах, консистентности структур данных, в повторном использовании модулей.

Экстремальное программирование:

Разновидность подхода, ориентированного на интерфейсы. Вместо графических редакторов программисты используют программные редакторы графических форм ввода-вывода информации, а дизайнеры потом «доукрашивают» эти формы. Решается один из минусов по проектрованию на уровне дизайнеров.

Вывод:

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

Подразумевается наличие программного инструмента управления документацией, доступного для понимания как полльзователям, так и дизайнерам с программистами.

Система документирования Sphinx

Наиболее распространенной системой для ведения документации сегодня является Sphinx (https://www.sphinx-doc.org) - программная разработка с открытым исходным кодом, написана на Python.

Отличительные особенности программы:

• формирование комплекта автономных веб-страниц с поддержкой поиска и тем оформления

• возможность размещения в качестве сайта на любом файловом хостинге без использования сервера баз данных и сервера веб-приложений (GitHub, BitBucket, GitLab)

• автоматическое создание структуры навигации по группе файлов на основе заголовков

• возможность использовать для работы любой тектовый редактор

• поддержка систем версионного контроля (Git например) для коллективной работы

• использование интуитивного языка разметки reStucturedText с богатым набором директив

• поддержка автодокументации программного кода

• кроссплатформенная работа на разных операционных системах (Windows, Linux, MacOS)

Плюсы для программной разработки:

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

• документацию легко «наращивать» с простого технического задания иллюстрациями прототипированных пользовательских форм, описанем алгоритмов работы и спецификациями программных модулей

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

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

• для планирования легко выделять новые разделы для недельных и месячных спринтов

• в документацию легко вставлять видеофрагменты и анимированные гифы

Язык разметки reStructuredText

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

Пример создания веб-страницы с помощью Sphinx.

Совместная версионная работа

Текстовый формат документации Sphinx позволяет широко использовать версионные подходы для коллективной работы. Приведем пример, в котором документация размещена на сервере с системой Git (это может быть интернет сервер GitHub или сервер в локальной сети GitLab). Два пользователя организовали свои связанные с сервером рабочие копии. Каждый внес изменение, но пользователь с более поздним изменением может увидеть конфликтующие места и поправить текст документации.

Пример коллективной работы с документацией Sphinx.

После всех исправлений второй пользователь сформировал веб-сайт документации и выложил его на сервер Git.

Сборка веб-сайта документации Sphinx.

Включение в документацию планов

Благодаря директивам .. todo:: и .. todolist:: можно включать в документацию специальные блоки, похожие по стилю на блоки сообщений и предупреждений. Можно также добавлять внутрь плановых блоков конструкции .. container:: <style-class>, где в поле <style-class> можно указать CSS класс в файле custom.css.

Подробнее о работе плановых блоков и сборку планов можно прочитать в разделе Планирование в Sphinx

План

Раздел - Рабочая документация в Sphinx - Критично (класс todo-danger)

№	Дата	Задача
Ответственный - в поиске
	не определена	Текст

Раздел - Рабочая документация в Sphinx - В ожидании (класс todo-warning)

№	Дата	Задача
Ответственный - в поиске
	не определена	Текст

Раздел - Рабочая документация в Sphinx - Намечено (класс todo-tip)

№	Дата	Задача
Ответственный - в поиске
	не определена	Текст

Организация разработки

Документация как процесс формализации удобно использовать на всех этапах разработки - при фиксации требований и технического задания, при разработке прототипа пользовательских интерфейсов с попутным формированием иерархии документов и описанием алгоримов работы программы.

В процессе ориентированной на документацию разработки все участники команды на разных этапах смогут видеть полную картину разрабатываемого продукта.

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