✨ Introduce needs-config-writer

[ubmarco]

📌 Description

Introduction of
https://needs-config-writer.useblocks.com

This greatly helps with distributed configs for Sphinx-Needs and ubCode / ubc.
Also dynamic and static configuration can be merged.

Any user of the docs() function will get a complete ubproject.toml generated into their confdir.
This is a declarative duplicate of all the dynamically generated Sphinx-Needs configuration.
It makes it possible to use tools such as ubCode or ubc without any further setup.
Adding static shared configuration is also possible, see shared.toml.

This is also a nice mechanism to transpile the metadata.yaml to the Sphinx-Needs 6 schema validation.

Absolute bazel cache paths for needs.json or the path to the shared plantuml file are turned into relative paths that resolve once the documentation was built once.

Tested this manually for this repo (see ubproject.toml) and https://github.com/eclipse-score/score.
ubCode works code out-of-the box, even when needs.json dependencies are not there.

The generated files can be committed to git and maintained on every docs-as-code update that comes with config changes. This is the recommended way, as it enables users to use ubCode / ubc without ever running Bazel. It also works when switching between branches. The other option is to gitignore the file and generate it on the first run of bazel run //:docs (or one of the other bazel run docs build commands).

Screenshot of ubCode for the score docs with the declarative configuration:

🚨 Impact Analysis

• This change does not violate any tool requirements and is covered by existing tool requirements
• This change does not violate any design decisions
• Otherwise I have created a ticket for new tool qualification

✅ Checklist

• Added/updated documentation for new or changed features
• Added/updated tests to cover the changes
• Followed project coding standards and guidelines

The existing tests use the new extension and cover it.
I have seen the CI failing during development due to this, and fixed all issues.

[github-actions]

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run //src:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.3.0) and connecting to it...
INFO: Invocation ID: 7456ecae-6050-43d7-88fc-9a7791dafa93
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)

Analyzing: target //src:license-check (72 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (73 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (123 packages loaded, 2168 targets configured)

Analyzing: target //src:license-check (129 packages loaded, 2435 targets configured)

Analyzing: target //src:license-check (135 packages loaded, 2484 targets configured)

INFO: Analyzed target //src:license-check (137 packages loaded, 4500 targets configured).
[12 / 13] checking cached actions
INFO: Found 1 target...
Target //src:license.check.license_check up-to-date:
  bazel-bin/src/license.check.license_check
  bazel-bin/src/license.check.license_check.jar
INFO: Elapsed time: 14.088s, Critical Path: 0.67s
INFO: 13 processes: 3 disk cache hit, 9 internal, 1 processwrapper-sandbox.
INFO: Build completed successfully, 13 total actions
INFO: Running command line: bazel-bin/src/license.check.license_check src/formatted.txt <args omitted>
usage: org.eclipse.dash.licenses.cli.Main [-batch <int>] [-cd <url>]
       [-confidence <int>] [-ef <url>] [-excludeSources <sources>] [-help] [-lic
       <url>] [-project <shortname>] [-repo <url>] [-review] [-summary <file>]
       [-timeout <seconds>] [-token <token>]

[github-actions]

The created documentation from the pull request is available at: docu-html

[AlexanderLanin]

We don't have a proper solution for storing such config files, so while I don't like it, it would be consistent to just write that file into each repository for now.

But there is a scenario I really don't like here:

• Someone updates the docs-as-code dependency with some insignificant metamodel change.
• PR is green, all is good, it gets merged
• main branch is clean
• Now the next user comes along and builds docs. Suddenly they have a change in their local toml file.

How about adding ubproject.toml to .gitignore for now? This avoid the use-case above, and while not perfect, it allows us to merge this without further discussions in time for v0.5.0-alpha S-CORE release.

[AlexanderLanin]

ubCode feedback:

• In docs-as-code I don't see a single local need. Only external needs. Are the 1000 items a limitation of the free license? (When clicking on that line, something should appear explaining why only 1000 items are shown)
• I cannot figure out how to filter to local needs. Filtering is way too complex.