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. A single ubproject.toml is generated at the git repo root — the one directory that is an ancestor of every source tree, so IDE tooling walking up from any open file (including files in mounted bundles, see Mount docs bundles) reaches it. The output location is resolved via find_git_root(), which works under bazel run and esbonio / direct Sphinx alike; a sandboxed bazel build has no git root and its copy is discarded.

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. Because it is regenerated every build, it is currently gitignored rather than committed. 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.