.. _`toml_sync`:

ubproject.toml sync
===================

The extension ``score_sync_toml`` provides configuration for the newly developed
Sphinx extension `needs-config-writer <https://needs-config-writer.useblocks.com/>`__.

The extension allows to write a declarative configuration file ``ubproject.toml``
that is required by the `ubCode VS Code extension <https://ubcode.useblocks.com>`__
and its companion CLI app `ubc <https://ubcode.useblocks.com/ubc/introduction.html>`__
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.