ubproject.toml sync

The extension score_sync_toml provides configuration for the newly developed Sphinx extension needs-config-writer.

The extension allows to write a declarative configuration file ubproject.toml that is required by the ubCode VS Code extension and its companion CLI app ubc to get hold of the Sphinx-Needs configuration.

The solution outlined here can serve as a template for how to build IDE extensions in a Bazel environment. IDE extensions need to know the configuration and file sets that are part of the project. This information is hidden in the build system, so a call is needed to extract this information and make it available to the IDE extension.

The basic idea is to stay with the programmed configuration system for Sphinx and Sphinx-Needs as it exists in S-CORE, but use it to generate the ubproject.toml file. The ubproject.toml file is generated into the directory holding the conf.py file (called confdir in Sphinx) and should be checked into the version control system alongside conf.py.

The ubproject.toml file is generated on each Sphinx build, so any changes to the Sphinx-Needs configuration are automatically reflected in the generated file. If changes are detected, a warning is emitted during the Sphinx build to remind the user to commit the updated ubproject.toml file. Changes may occur because docs-as-code updated a configuration or a new Sphinx-Needs version added configuration.

Committing the generated ubproject.toml file allows the IDE extension to work without requiring any Sphinx build to be performed first. For a fully complete network of need items, required external or imported needs.json files must first be generated by Bazel.

The command line tool ubc uses the same configuration as ubCode and can be used to lint and format all RST files in any of the S-CORE documentations. ubc also has features for exporting traceability data to specific file formats or performing diff and impact analysis.