- PVSM.RU - https://www.pvsm.ru -
Работая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.
Описание должно было в себя включать:
Объем документирования очень большой. Данные во всех документах связаны друг с другом, поэтому при изменении проекта (например добавления нового требования), приходится редактировать практически все документы. Плюс к этому можно где-то ошибиться или забыть поправить, что приводит к ошибкам в документации.
Далее в статье я расскажу как я решил эту проблему.
Поэтому было решено использовать автоматизированные средства, которые создают все документы, используя данные из первичных документов — таблиц в формате CSV, XML документов. При любых изменениях в проекте — можно запустить заново генерацию комплекта документации.
Таблицы в формате CSV удобно редактировать в табличном процессоре. Данные о проекте (текущую версию, наименование, совместимое оборудование) хранил в формате XML.
Описание реализации требований уже содержится в doxygen комментариях к исходному коду. Doxygen специально для таких случаев может генерировать документацию в формате XML.
Генератор документации на основе шаблонов документов создает LaTeX документы, которые уже в PDF формате передаются заказчику.
(Шаблоны документов) -->: Генератор документации:: LaTeX
(Требования) -->: Генератор документации:: CSV
(Планы) -->: Генератор документации:: LaTeX
(Описание реализации) -->: Генератор документации:: XML
(Описание тестов) -->: Генератор документации:: XML
(Обнаруженные проблемы) -->: Генератор документации:: CSV
: Генератор документации: --> (Комплект документации): LaTeX
Для реализации такой системы создания документации мне потребовалась утилита обработки шаблонов и скрипт сборки.
Скрипт сборки я реализовал в Makefile. Скрипт выполнял следующие действия:
Ключевой элемент системы — утилита обработки шаблонов документов.
Исходные коды можно получить: github.com/krotos139/pytemplate [1]
Или установить утилиту можно с помощью команды:
sudo pip install pytemplateproc
Использование утилиты: pytemplate.py [options]
Опции:
В шаблонах содержится информация — данные из каких внешних источников ему нужны. Утилита во время обработки шаблона подгружает необходимые данные, и использует их при заполнении шаблона данными.
Поддерживаемые источники данных:
В утилиту передается файл шаблона и путь до результирующего файла. Пути до источников данных в программу не передаются, так как они все определены в шаблоне, и один шаблон может использовать множество разных источников данных.
Пример шаблона:
{%- 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 Код} \hline
endfirsthead
caption*{it{Продолжение таблицы} ref{tab:reports}}\hline
{centering Код} \hline
endhead
{%- for item in docs %}
{{ item.id }} } } } } \hline
{%- endfor %}
end{longtable}
newpage
Использование утилиты pytemplate позволяет создавать документы и отчеты по шаблонам, используя для заполнения шаблонов данные. При этом данные можно хранить в удобном формате электронных таблиц или баз данных.
Автор: krotos139
Источник [2]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/python/116621
Ссылки в тексте:
[1] github.com/krotos139/pytemplate: https://github.com/krotos139/pytemplate
[2] Источник: https://habrahabr.ru/post/280476/
Нажмите здесь для печати.