Automation of paperwork

Working on projects related to avionics, I needed to issue several sets of documentation with a complete description of the project. Also, it was necessary to take into account the requirements of many GOSTs for registration and for the content of documentation, such as ESPD, KT-178B and others.

The description should include:

• Software Development Plans
• Software Requirements
• Description of the implementation of software requirements
• Traceability (compliance) tables of software requirements and implementation
• Description of software tests (Software Verification Examples and Procedures)
• Traceability (compliance) tables of software requirements and tests
• Problem Report
• Configuration pointer (description of software version and compatibility with third-party software and hardware)

The volume of documentation is very large. The data in all documents are related to each other, so when changing a project (for example, adding a new requirement), almost all documents have to be edited. Plus, you can somewhere make a mistake or forget to fix it, which leads to errors in the documentation.
')


Further in the article I will tell you how I solved this problem.

Documentation Generator Architecture

Therefore, it was decided to use automated tools that create all documents using data from primary documents - tables in CSV format, XML documents. With any changes in the project - you can re-generate the generation of a set of documentation.

Tables in CSV format are conveniently edited in a tabular processor. Data about the project (current version, name, compatible equipment) was stored in XML format.

The description of the implementation of the requirements is already contained in doxygen source code comments. Doxygen specifically for such cases can generate documentation in XML format.

Documentation generator based on document templates creates LaTeX documents, which are already in PDF format transferred to the customer.

Documentation Generator

To implement such a system for creating documentation, I needed the template processing utility and the build script.

I implemented the build script in the Makefile. The script performed the following actions:

• I got the source
• Generated XML descriptions using Doxygen
• Gathered all the necessary documents from templates using pytemplate.py
• Generated PDFs by LaTeX
• Formed a folder tree and created a disk image for recording
• compiled the necessary accompanying documentation (file with title pages, disk label)

A key element of the system is the document template processing utility.

Template Processing Utility

Source codes can be obtained: github.com/krotos139/pytemplate

Or you can install the utility with the command:

sudo pip install pytemplateproc 

Usage utility: pytemplate.py [options]
Options:

• --version Display version
• -h, --help Display startup key information
• -t TEMPLATE, --template = TEMPLATE Specify the path to the template file
• -o OUTPUT, --output = OUTPUT Specify the path to the output file
• -f FORMAT, --format = FORMAT The format of the template file, can take values ​​(odt and text)
• -a ARG, --arg = ARG Additional entity for the template

The templates contain information - data from which external sources it needs. The utility during the processing of the template loads the necessary data, and uses it when filling the template with data.

Supported data sources:

• CSV table (Can be edited in Exel subject to certain rules)
• XML document
• Text file
• SQLite database
• MD5 function from file
• File data retrieval function

The template file and the path to the resulting file are transferred to the utility. The paths to the data sources to the program are not transmitted, since they are all defined in the template, and one template can use many different data sources.

Template example:

 {%- 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 

Conclusion

Using the pytemplate utility allows you to create documents and reports on templates, using data to fill templates. In this case, data can be stored in a convenient format of spreadsheets or databases.