The build currently supports Linux environments.
Follow instructions and setup bazelisk to manage your bazel version based on the .bazelversion file.
$ bazel test //:format.check
$ bazel run //:format.fix
Score supports multiple methods for generating documentation, tailored to different workflows:
- Bazel-based builds for clean, sandboxed outputs.
- Incremental builds for quick iterations during development.
- IDE integration for live previews, live warnings and even faster iterations.
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:docsThe output will be located in bazel-bin/docs/docs/_build/html.
For local changes and faster feedback, use the incremental build. This method generates the documentation directly in the _build directory.
bazel run //docs:incrementalUnlike IDE integration, which renders only the current file, this approach is ideal for quickly verifying edits across the entire documentation during development.
For live previews, warnings, and linting during development, integrate Esbonio with your IDE (e.g., VS Code):
bazel run //docs:ide_supportVS 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.
- Bazel builds output to bazel-bin/docs/docs/_build/html.
- Incremental builds output to _build.
- 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.