Use specification items to generate documentation

[Sebastian Huber]

Hello,

for the RTEMS pre-qualification activity we need a specification of 
RTEMS. I would like to use this opportunity to move structured 
information which is present in hand written and hand formatted content 
in the RTEMS documentation into a structured data format (YAML). 
Documentation source files can be generated from the YAML files. Having 
information available in an easily machine readable format with 
meta-information gives us a lot of flexibility. For example to adjust 
the presentation we just have to change the generator program and not 
the hand written content. The presentation of things may depend on the 
standard of interest, e.g. ECSS, IEC 61508, ISO 26262, DO-178C, etc.

To get started, I would like to use the glossary of terms and the 
application configuration as a use case. The conversion from hand 
written and hand formatted content to generated content needs three things:

1. A definition of the data format (YAML with Doorstop attributes)

2. The specification items in the defined data format.

3. A generator program which uses the specification items as input and 
outputs the documentation source files.

The new build system introduced build specification items in the RTEMS 
sources under "spec/build". I would like to place all of the RTEMS 
specification under the "spec" directory. For the glossary I propose to 
use "spec/glossary". For the application configuration categories I 
propose "spec/cfg" and for the application configuration options 
"spec/cfg/opt". The layout of the application configuration items 
enables an easy reassignment of options to categories.

The definition of the data format should be added to the RTEMS Software 
Engineering manual to the Software Requirements Engineering chapter.

The generator program should be written in Python and placed into the 
rtems-tools repository. The generator program needs paths to the RTEMS 
sources and the RTEMS documentation sources. The paths should be 
specified via the command line.

For a proof-of-concept please have a look at the attached two patches.

What do you think of it?

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-spec-cfg-Add-application-configuration.patch
Type: text/x-patch
Size: 10468 bytes
Desc: not available
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200108/d48a6396/attachment.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0002-spec-glossary-Support-a-glossary.patch
Type: text/x-patch
Size: 3552 bytes
Desc: not available
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200108/d48a6396/attachment-0001.bin>