Preparing Spexygen DocumentationSpexygen Example

As shown in the spexygen workflow diagram, Spexygen documentation generation is handled by the Python script spexygen.py. This script processes the input files in two passes. In the first pass (called "trace"), the spexygen.py script parses the files for the special Spexygen commands and collects the information about the dependencies among the various artifacts (based on their UIDs). In the second pass (called "gen"), the spexygen.py script generates the output-files by replacing the special forward traceability commands (@ui_fw_trace and @code_fw_trace) with the actual traceability links collected during the first pass.

Spexygen Configuration File

Similar to Doxygen, Spexygen is configured by an external configuration file with the default name spex.json. That file specifies about the input files and output directory and files. The file is structure according to the JSON format↑. Below is an annotated example of spex.json file:

    {
[1] "trace": [
        "../example/srs.dox",
        "../example/dev.dox",
        "../example/inc",
        "../example/src",
        "../example/test",
        "../example/code.dox"
    ]

[2] "gen-dir": "spex",
[3] "gen-inc": "Spexyinc",
[4] "gen": [
        "../example/srs.dox",
        "../example/dev.dox",
        "../example/inc",
        "../example/src",
        "../example/test"
        "../example/code.dox"
    ],
    }

[1] The "trace": JSON array contains a list of the input files that Spexygen will "trace".

Remarks: The "trace": array is optional and if it is not provided, Spexygen will "trace" the files specified in the "gen": array.

[2] The "gen-dir": JSON string specifies the output-directory into which Spexygen will generate the output

Remarks: The "gen-dir": JSON string is optional and if not provided, <i>Spexygen</i> will use the default directory spex`

[3] The "gen-inc": JSON string specifies the spexygen include-file for Doxygen, which contains the list of the generated files. It is intended for inclusion in the Doxyfile. The spexygen include-file is generated in the output-directory.

Remarks: The "gen-inc":` JSON string is optional and if not provided, Spexygen will NOT generate the include-file.

[4] The "gen": JSON array contains a list of the files that Spexygen will generate by replacing the special forward traceability commands (@ui_fw_trace and @code_fw_trace) with the actual traceability links collected during the "trace" pass.

Attention: The order of the files in the "gen": array is important. In particular, any external documenation (separated from the code) must be listed after the elements that it documents.

Running Spexygen

The spexygen.py Python script can be executed from a command prompt. Typically, you run the script in the directory, where you have your spex.json script.Here is an example run:

cd spexygen/doc  <-- the directory with the spex.json config file
python ../spexygen.py

Spexygen: traceable technical documentation system 2.0.0
Copyright (c) 2005-2024 Quantum Leaps, www.state-machine.com

Tracing: ../example/exa.dox
Tracing: ../example/srs.dox
Tracing: ../example/dev.dox
Tracing: ../example/inc/header.h
Tracing: ../example/src/source.c
Tracing: ../example/test/test1.c
Tracing: ../example/test/test2.c
Generating: spex/exa.dox
Generating: spex/srs.dox
Generating: spex/dev.dox
Generating: spex/header.h
  No forward trace for UID: "Foo"
  No forward trace for UID: "Foo_inst"
Generating: spex/source.c
Generating: spex/test1.c
Generating: spex/test2.c

Note: The spexygen.py script takes one command-line parameter, which is the name of the configuration file. If not provided, the default name is spex.json.

Remarks

The spexygen.py Python script is also available in the PyPi package manager↑ and can be installed with the standard Python package installer pip:

pip install spexygen

After such installation, you run Spexygen simply as follows:

spexygen

Either way, depending on your settings Spexygen will create the output-directory (e.g., spex) with all the generated files.

Spexygen Include File

Spexygen can generate the spexygen include-file for Doxygen, which contains the list of the generated files. It is intended for inclusion in the Doxyfile. The spexygen include-file is generated in the output-directory. Here is an example:

INPUT += \
spex/exa.dox \
spex/srs.dox \
spex/dev.dox \
spex/header.h \
spex/source.c \
spex/test1.c \
spex/test2.c

Doxygen Configuration File

The Spexygen output (plus other files) can be now fed to Doxygen. However, before you can run Doxygen, you need the Doxygen configuration file↑. That configuration file must include the spexygen special commands and the files generated by Spexygen. Here is an example of an annotated Doxyfile with these elements:

[1] @INCLUDE = $(SPEXYGEN)/Spexyfile
[2] INPUT = main.dox
[3] @INCLUDE = spex/Spexyinc
[4] INPUT += ...

[1] The Doxygen \@INCLUDE tag includes the Spexyfile located in the $(SPEXYGEN) directory defined here by means of an environment variable.

Attention: The SPEXYGEN environment variable must be defined in your system to point to the spexgyen installation directory.

[2] The INPUT tag↑ specifies the input files for Doxygen. Here you can specify files that you wish to include in the Doxygen output, but which have not been processed by Spexygen.

[3] This Doxygen \@INCLUDE = spex/Spexyinc tag includes the spexgyen-include file with the Doxygen input generated by Spexygen.

[4] Any additional Doxygen INPUT (not produced by spexyen) can be specified as well (please note the += operator as opposed to =)

Running Doxygen

Once the $(SPEXYGEN) environment variable has been defined, Doxygen can be run as usual from the directolry with the Doxyfile:

Doxygen

Combining Spexygen & Doxygen

In practice, most convenient is combining Spexygen and Doxygen and run both automatically one after another. Here is an example Windows batch file that automates the process (see spexygen/doc/make.bat):

Note: The provided make.bat can generate HTML↑ and PDF↑ output formats.

@setlocal

@echo usage:
@echo make
@echo make -PDF

:: tools (adjust to your system)----------------------------------------------
:: Doxygen/Spexygen tools
@set DOXYGEN=Doxygen
@set SPEXYGEN=..

@echo Generate Spexygen tracing ----------------------------------------------
rmdir /S /Q  .\spex
python %SPEXYGEN%/spexygen.py spex.json

::============================================================================
@if "%1"=="-PDF" goto PDF

@echo Generate HTML Documentation --------------------------------------------
@set HTML_OUT=html

@echo.
@echo cleanup
rmdir /S /Q %HTML_OUT%

@echo generating HTML...
%DOXYGEN% Doxyfile

::qclean %HTML_OUT%
goto END

:PDF
@echo Generate PDF Documentation --------------------------------------------
@set LATEX_OUT=latex

@echo.
@echo cleanup
rmdir /S /Q  %LATEX_OUT%

@echo generating LATEX...
%DOXYGEN% Doxyfile-PDF

:: Generate LaTex/PDF Documentation...
@echo generating PDF...
@cd %LATEX_OUT%
@call make.bat
@copy refman.pdf ..\DOC-MAN-SPX.pdf
@cd ..
rmdir /S /Q  %LATEX_OUT%

:END
@echo Final cleanup ----------------------------------------------------------
rmdir /S /Q  .\spex

@endlocal

Preparing Spexygen DocumentationSpexygen Example