From 7cd51515971922505507c8d3f85c6555226ff1f2 Mon Sep 17 00:00:00 2001 From: Ignas Anikevicius <240938+aignas@users.noreply.github.com> Date: Sun, 15 Nov 2026 17:59:32 +0900 Subject: [PATCH] docs(coverage): set the bzl default domain and link the API references The coverage guide did not set the `bzl` default domain, so it couldn't use cross-references to the API docs. Set it and link the rules, attributes and functions that the guide mentions. --- docs/coverage.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/coverage.md b/docs/coverage.md index 1eeb67c808..87a81ea900 100644 --- a/docs/coverage.md +++ b/docs/coverage.md @@ -1,3 +1,6 @@ +:::{default-domain} bzl +::: + # Setting up coverage As of Bazel 6, the Python toolchains and bootstrap logic supports providing @@ -11,7 +14,7 @@ when configuring toolchains. Enabling the coverage support bundled with `rules_python` just requires setting an argument when registering toolchains. -For Bzlmod: +For Bzlmod, use {obj}`python.toolchain`: ```starlark python.toolchain( @@ -20,7 +23,7 @@ python.toolchain( ) ``` -For WORKSPACE configuration: +For WORKSPACE configuration, use {obj}`python_register_toolchains`: ```starlark python_register_toolchains( @@ -29,12 +32,12 @@ python_register_toolchains( ``` :::{note} -This will implicitly add the version of `coverage` bundled with -`rules_python` to the dependencies of `py_test` rules when `bazel coverage` is -run. If a target already transitively depends on a different version of -`coverage`, then the behavior is undefined -- it is undefined which version comes -first in the import path. If you find yourself in this situation, then you'll -need to manually configure coverage (see below). +This will implicitly add the version of `coverage` bundled with `rules_python` +to the dependencies of {obj}`py_test` rules when `bazel coverage` is run. If a +target already transitively depends on a different version of `coverage`, then +the behavior is undefined -- it is undefined which version comes first in the +import path. If you find yourself in this situation, then you'll need to +manually configure coverage (see below). ::: :::{note} @@ -45,18 +48,19 @@ wheel, `configure_coverage_tool = True` produces no coverage tool and `bazel coverage` emits empty lcov data; manually configure coverage (see below) instead. -`py_runtime` warns when this happens. The warning is emitted during analysis, -for the runtime toolchain resolution selected and only when coverage is being -collected, so it does not fire for the many platforms toolchains are +{obj}`py_runtime` warns when this happens. The warning is emitted during +analysis, for the runtime toolchain resolution selected and only when coverage +is being collected, so it does not fire for the many platforms toolchains are registered for but a given build never uses. ::: ## Manually configuring coverage To manually configure coverage support, you'll need to set the -`py_runtime.coverage_tool` attribute. This attribute is a target that specifies -the coverage entry point file and, optionally, client libraries that are added -to `py_test` targets. Typically, this would be a `filegroup` that looked like: +{attr}`py_runtime.coverage_tool` attribute. This attribute is a target that +specifies the coverage entry point file and, optionally, client libraries that +are added to `py_test` targets. Typically, this would be a `filegroup` that +looked like: ```starlark filegroup(