Автоматизация оформления документации

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

Описание должно было в себя включать:

• Планы разработки ПО
• Требования к ПО
• Описание реализации требований к ПО
• Таблицы трассируемости(соответствия) требований к ПО и реализации
• Описание тестов на ПО (Примеры и процедуры верификации ПО)
• Таблицы трассируемости(соответствия) требований к ПО и тестов
• Отчет об обнаруженных проблемах
• Указатель конфигурации(описание версии ПО и совместимости со сторонним ПО и оборудованием)

Объем документирования очень большой. Данные во всех документах связаны друг с другом, поэтому при изменении проекта (например добавления нового требования), приходится редактировать практически все документы. Плюс к этому можно где-то ошибиться или забыть поправить, что приводит к ошибкам в документации.

Далее в статье я расскажу как я решил эту проблему.

Архитектура генератора документации

Поэтому было решено использовать автоматизированные средства, которые создают все документы, используя данные из первичных документов — таблиц в формате CSV, XML документов. При любых изменениях в проекте — можно запустить заново генерацию комплекта документации.

Таблицы в формате CSV удобно редактировать в табличном процессоре. Данные о проекте (текущую версию, наименование, совместимое оборудование) хранил в формате XML.

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

Генератор документации на основе шаблонов документов создает LaTeX документы, которые уже в PDF формате передаются заказчику.

Генератор документации

Для реализации такой системы создания документации мне потребовалась утилита обработки шаблонов и скрипт сборки.

Скрипт сборки я реализовал в Makefile. Скрипт выполнял следующие действия:

• Получал исходники
• Генерировал XML описания с помощью Doxygen
• Собирал все необходимые документы из шаблонов с помощью pytemplate.py
• Генерировал PDF-ки LaTeX-ом
• Формировал дерево папок и создавал образ диска для записи
• формировал необходимую сопроводительную документацию (файл с титульными листами, этикетку диска)

Ключевой элемент системы — утилита обработки шаблонов документов.

Утилита обработки шаблонов

Исходные коды можно получить: github.com/krotos139/pytemplate

Или установить утилиту можно с помощью команды:

sudo pip install pytemplateproc 

Использование утилиты: pytemplate.py [options]
Опции:

• —version Отобразить версию
• -h, —help Отобразить информацию о ключах запуска
• -t TEMPLATE, —template=TEMPLATE Указать путь до файла шаблона
• -o OUTPUT, —output=OUTPUT Указать путь до выходного файла
• -f FORMAT, —format=FORMAT Формат файла шаблона, может принимать значения (odt и text)
• -a ARG, —arg=ARG Дополнительная сущность для шаблона

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

Поддерживаемые источники данных:

• CSV таблица (Может быть отредактирована в Exel при соблюдении определенных правил)
• XML документ
• Текстовый файл
• SQLite база данных
• Функция MD5 от файла
• Функция получения данных о файле

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

Пример шаблона:

{%- set docs = load_csv("database2.csv")  %} \subsection{Список документов}  \begin{longtable}{|m{2cm}|m{3cm}|m{3cm}|m{3cm}|m{3cm}|} \caption{Списки документов} \label{tab:reports}\\\hline {\centering Код} & {\centering Наименование} & {\centering Стандарт} & {\centering Децимальный номер} & {\centering Инвентарный} \\\hline \endfirsthead \caption*{\it{Продолжение таблицы} \ref{tab:reports}}\\\hline {\centering Код} & {\centering Наименование} & {\centering Стандарт} & {\centering Децимальный номер} & {\centering Инвентарный} \\\hline \endhead {%- for item in docs %} {{ item.id }} & {{ item.name }} & {{ item.ref }} & {{ item.sign }} & {{ item.inv }} \\\hline {%- endfor %} \end{longtable} \newpage 

Заключение

Использование утилиты pytemplate позволяет создавать документы и отчеты по шаблонам, используя для заполнения шаблонов данные. При этом данные можно хранить в удобном формате электронных таблиц или баз данных.

ссылка на оригинал статьи https://habrahabr.ru/post/280476/