Software Version Description (SVD) Template

Documentation as Code

What is this thing?

This is both a GitHub Template repository and a usable template for a MIL-STD-498 DID-compliant Software Version Description in reStructuredText. This repo contains the following items:

• A Data Item Descripttion for a Software Version Description (SVD) in ASCII text format
• A DID-compliant SVD outline using all the required DID sections (in reStructuredText format)
• Sample document styles for rst2pdf
• Sample title-page, logo, and system diagram
• Sample version table using OpenEmbedded SW manifest
• Sample ChangeLog data generated via gitchangelog
• Python source for the system diagram
• A tox file and Makefiles (to build things from source)

We use make and rst2pdf to build the full SVD document, and the diagrams tool to generate system architecture and related software diagrams.

Note

Currently we use the VCTLabs fork of diagrams in order to have the affinity icon set for networked/embedded systems.

Contents after a fresh clone:

./
├── CONTRIBUTING.rst
├── LICENSE
├── Makefile
├── README.rst
├── pyproject.toml
├── requirements-dia.txt
├── resources  # these are references or pre-inputs to the build workflow
│   ├── SVD_DID_DI-IPSC-81443.txt     # Software Version Description DID
│   ├── example-title-page.rst        # example title page source
│   └── acme_webservice.py            # source code for the example system diagram
├── SVD
│   ├── EU_SVD.rst                    # source code for the document/template
│   ├── Makefile
│   ├── images                        # graphics sources for document build
│   │   ├── acme.png
│   │   └── acme.svg
│   └── styles                        # old/new format style sheets
│       ├── rst2pdf.style
│       └── SVD.yaml
├── tox.ini                           # workflow configuration
└── toxfile.py                        # workflow plugin file

Software Stack and Tool Dependencies

Install the following with your system package manager to run the workflows:

• Python - at least version 3.8
• Tox - at least version 4.2
• Graphviz - any recent version should work
• make and bash - any recent versions should be fine

Now you can use the workflow commands to install the remaining dependencies using Python virtual environments inside the project directory and use the tools for "building" diagrams and document sources.

Optional dependencies

The graph command shown below is completely optional and is therefore not required to generate/build graphics or documents. This ancillary command is only used to rebuild/add new resource content used by the diagrams package. The required dependencies include Graphviz, along with the following:

• round
• inkscape
• imagemagick/graphicsmagick
• ttf-open-sans
• fontconfig
• xdg-utils

Note that package names for the above can differ between package managers, so search accordingly (remember you only need Graphviz for the document workflows).

Usage

From inside the repository checkout, use tox list to view the list of environment descriptions:

$ tox list
...
additional environments:
sync           -> Install repolite and use it for cloning diagram workflow deps
do             -> Run cmd following "--" from the sync env, e.g. "tox -e do -- repolite --show"
graph          -> Build new content for the diagrams package (run sync first to install the source)
gen            -> Generate a new diagram from your python source file
changes        -> Generate full or partial changelog; use git delta syntax for changes-since

To build the SVD document, run the following 3 workflow commands in the order shown:

$ tox -e sync   # install repolite and clone the diagram repos to ext/ folder
$ tox -e gen    # install diagrams and generate the architecture diagram from python source,
                # then move the output .png file to SVD/images/ folder
$ tox -e build  # install rst2pdf and build the PDF document from .rst source and .svg/.png images

For extended sessions, use the virtual environment created by the build command above for document work:

$ source .tox/build/bin/activate
(build) $ $EDITOR svd/EU_SVD.rst        # make content changes
(build) $ $EDITOR svd/styles/*.style    # make style changes
(build) $ $EDITOR svd/Makefile          # change rst2pdf args or other build options
(build) $ make                          # (re)build PDF document
(build) $ make clean                    # force a new build, eg, after style changes
(build) $ evince svd/EU_SVD.pdf         # view rendered document
(build) $ deactivate                    # to exit the virtual environment

Similarly, use the virtual environment created by the gen command for diagram work:

$ source .graph/bin/activate
(.graph) $ $EDITOR resources/acme_webservice.py  # make content changes
(.graph) $ python resources/acme_webservice.py   # rebuild the diagram
(.graph) $ deactivate                            # to exit the virtual environment

Points to note:

• you only need to sync once (after a fresh checkout)
• you only need to run gen if the python source file is changed
• run tox -e clean,build any time to view a fresh PDF

In addition to the gen command, the default makefiles will also build diagrams from .dot code if you drop a (graphviz) dot file in the SVD/images/ folder and use the resulting .svg file in your .rst source document.

Contributing

Please read CONTRIBUTING for details on the code of conduct and some general guidance on submitting pull requests.

Pre-commit

This repo is pre-commit enabled for python/rst source and file-type linting. The checks run automatically on commit and will fail the commit (if not clean) and perform simple file corrections. For example, if the mypy check fails on commit, you must first fix any fatal errors for the commit to succeed. That said, pre-commit does nothing if you don't install it first (both the program itself and the hooks in your local repository copy).

You will need to install pre-commit before contributing any changes; installing it using your system's package manager is recommended, otherwise install with pip into your local user environment using something like:

$ sudo emerge pre-commit  --or--
$ pip install pre-commit

then install the hooks into the repo you just created from the template:

$ cd your_new_SVD_repo/
$ pre-commit install

It's usually a good idea to update the hooks to the latest version:

$ pre-commit autoupdate

Most (but not all) of the pre-commit checks will make corrections for you, however, some will only report errors, so these you will need to correct manually.

Automatic-fix checks include black, isort, autoflake, and miscellaneous file fixers. If any of these fail, you can review the changes with git diff and just add them to your commit and continue.

If any of the mypy or rst source checks fail, you will get a report, but then you must fix any errors before you can continue adding/committing.

To see a "replay" of any rst check errors, run:

$ pre-commit run rst-backticks -a
$ pre-commit run rst-directive-colons -a
$ pre-commit run rst-inline-touching-normal -a

To run all pre-commit checks manually, try:

$ pre-commit run -a

License

This project is licensed under the MIT license - see the LICENSE file for details.