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

    Работая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.

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


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



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



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



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

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

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

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


    Диаграмма создания документации
    Руководитель --> (Планы)
    Руководитель -> (Требования)
    Руководитель -> (Описание тестов)
    Руководитель --> (Обнаруженные проблемы)
    (Требования) -> Программисты
    Программисты --> (Программный код)
    (Программный код) --> Doxygen
    Doxygen --> (Описание реализации)

    (Шаблоны документов) -->: Генератор документации:: LaTeX

    (Требования) -->: Генератор документации:: CSV
    (Планы) -->: Генератор документации:: LaTeX
    (Описание реализации) -->: Генератор документации:: XML
    (Описание тестов) -->: Генератор документации:: XML
    (Обнаруженные проблемы) -->: Генератор документации:: CSV

    : Генератор документации: --> (Комплект документации): LaTeX


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


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

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



    Диаграмма последовательности генерации документации
    GIT->«Генератор документации»: Исходные тексты
    «Генератор документации»->Doxygen: Исходные тексты
    Doxygen->«Генератор документации»: XML описание
    «Данные проекта»->«Генератор документации»: Шаблоны
    «Генератор документации»->PyTemplate: Шаблоны
    «Данные проекта» -> PyTemplate: CSV, XML
    PyTemplate->LaTeX: LaTeX документы
    LaTeX->«Генератор документации»: PDF документы


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

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


    Исходные коды можно получить: 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 позволяет создавать документы и отчеты по шаблонам, используя для заполнения шаблонов данные. При этом данные можно хранить в удобном формате электронных таблиц или баз данных.
    • +7
    • 13.6k
    • 2
    Share post

    Similar posts

    Comments 2

      0
      Тема интересная, хотелось бы более подробного описания и примеров.

    Only users with full accounts can post comments. Log in, please.