Score Platform

Building

Development environment

The build currently supports Linux environments. Follow instructions to set up your development environment.

Some important commands to get you started:

# Check formatting
bazel test //:format.check

# Fix formatting
bazel run //:format.fix

# Check for license headers
bazel run //:copyright.check

# Fix license headers
bazel run //:copyright.fix

Building Documentation

Score supports multiple methods for generating documentation, tailored to different workflows:

1. Bazel-based builds for clean, sandboxed outputs.
2. Incremental builds for quick iterations during development.
3. IDE integration for live previews, live warnings and even faster iterations.
4. IDE independent live preview for live previews of documentation without IDE integration.

Bazel-based Build

This method ensures clean and isolated documentation builds in a controlled Bazel environment. It is best suited for CI pipelines or production-ready outputs, although it takes longer compared to incremental builds.

bazel build //docs:docs

The output will be located in bazel-bin/docs/docs/_build/html.

Incremental build

For local changes and faster feedback, use the incremental build. This method generates the documentation directly in the _build directory.

bazel run //docs:incremental

Unlike IDE integration, which renders only the current file, this approach is ideal for quickly verifying edits across the entire documentation during development.

IDE integration

For live previews, warnings, and linting during development, integrate Esbonio with your IDE (e.g., VS Code):

bazel run //docs:ide_support

VS Code: Install the Esbonio extension in VS Code. After installation, restart your IDE. You should now have live preview available when you open a .rst file. Note: if the extension was already installed when you ran the ide_support command, you will need to restart your IDE.

For features like type detection in conf.py or extensions, point your IDE to the .venv_docs virtual environment.

Re-run //docs:ide_support if you update Sphinx extensions or other dependencies.

IDE independent live preview

For a documentation live preview independent of an IDE (CLI + browser only), sphinx-autobuild can be used. This will automatically rebuild the preview after save and have it available at http://127.0.0.1:8000

bazel run //docs:live_preview

Testing

Use the following command to run all available tests:

$ bazel test //...

However it's also possible to run specific tests or set of tests.

To run all tests of a certain language use the command below, here an example for python.

$ bazel query 'kind(py.*, tests(//...))' | xargs bazel tests

Grouping of tests via tags is also supported:

$ bazel test --test_tag_filters=docs-build

You can add as many tags as you like, as long as a test has at least one of the tags it will be executed. *Note: In order for a test to be picked up by this it has to be marked with the tag. Read more here

Test coverage for Python

To generate coverage data for Python test targets, run the following command:

bazel coverage --combined_report=lcov //docs:score_metamodel_test

This generates a coverage file _coverage_report.dat in the folder bazel-out/_coverage for the Python test target //docs:score_metamodel_test. Replace the target to execute coverage for a different test target.

You can use the tool genhtml to generate an HTML report as follows:

genhtml --ignore-errors mismatch --branch-coverage --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat"

This generates an HTML report in the folder genhtml which shows both line and branch coverage. Open file genhtml/index.html in a browser to show the report.

The tool genhtml is part of the lcov toolchain (https://github.com/linux-test-project/lcov). You can install it on Debian/Ubuntu system as follows:

sudo apt update
sudo apt install lcov

Notes

Output Locations

• Bazel builds output to bazel-bin/docs/docs/_build/html.
• Incremental builds output to _build.

Troubleshooting

• Restart your IDE if live previews or warnings are not working after running ide_support.
• Ensure your virtual environment is up-to-date by re-running //docs:ide_support when dependencies change.