Integration
Compatibility
Requires at least Python 3.8.
Requires at least Sphinx 6.2.
dox_trace is optimized for the Read the Docs Sphinx Theme. For convenience, use the dox_style extension enhances the original RTD theme by some nice features.
The officially supported platforms are Windows, Linux and macOS.
Configuration
To use the dox_trace extension in your workspace, you have to reference it in conf.py:
In the following example, the dox_trace extension was copied into an _ext folder, see also
Installation.
EXTENSION_ROOT = Path('_ext')
sys.path.extend([str(path.resolve()) for path in EXTENSION_ROOT.glob('*')])
extensions = [
...,
'sphinxcontrib.jquery',
'dox_trace'
]
dox_trace is using jQuery. sphinxcontrib.jquery needs to be added as extension to conf.py
as well.
The extension can be configured with the following parameters:
dox_trace_custom_attributes: definition of custom attributesdox_trace_allow_undefined_refs: allowing references to non-existing targetsdox_trace_allow_deprecated: enabling backward compatibility for specification typesdox_trace_security_backward: enabling backward compatibility for security attributedox_trace_test_setups_backward: enabling backward compatibility for test_setups attributedox_trace_dim_root: exporting to Dim files
Folder Structure
There is no limitation regarding the folder structure from tooling perspective, but please follow project specific guidelines. When exporting to Dim, the Sphinx folder structure is used to create Dim files, e.g.:
a/b/c.rst --> a/b/c.dim
File Structure
There is also no limitation regarding the file structure, but again, please follow project specific guidelines.
SRS_<string>_<string>.SMD|SWA_<string>_<string>.SWA_<string>_<string>.SMD_<string>_<string>.All IDs must contain exactly two _.
In earlier version of this extensions, the rules were less strict. It was only checked if the ID
starts with SMD|SWA_. To re-enable this behavior, set the config variable
dox_trace_tolerant_naming_convention in conf.py to True:
dox_trace_tolerant_naming_convention = True
When exporting to Dim, a folder is injected into the path depending on the first element of the ID,
either srs, swa or smd.
Example:
<documentation root>/a/b/c.rst --> <Dim export root>/swa/a/b/c.dim
Specification Structure
Follow the syntax described in the User Documentation. dox_trace will automatically check if the
syntax is correct during the build except attributes which have fixed enums values like status or
asil. These values are checked when exporting to Dim and running the dim check.
Verifier
Include the documentation build in a verifier (no incremental build). Also export the specifications
to Dim files and run the dim check. The verifier must reject the commit if:
the exit code is not 0 for Sphinx / Dim
Sphinx / Dim hangs and is terminated due to a timeout
This ensures that only syntactically correct and consistent files are merged to the repository. It also helps to prevent safety and security issues.
Review
Always review the HTML output to check that the specifications are displayed as expected.
Always perform a sanity check of the Dim export, e.g. are files written, is something obvious missing and do some spot checks.
Official Builds
When building the official documentation (with or without a Dim export) always perform a complete
build, not an incremental build. Make sure that the build folder does not exist before starting
the build.
Bugs
Bugs must be tracked on regular basis, see also Bug Tracking and Feature Planning. Evaluate if the reported bugs have an impact on your project and take appropriate actions like updating dox_trace in that project to a newer version.
Version
It must be ensured that only the correct (qualified) version of this tool is used.
Log the version of dox_trace in the official CI-jobs.
Compare this version with the version specified for the project.