Skip to content

feat: build host-only doc tools in host config via aspect_bazel_lib platform_transition_binary #635

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
umaucher wants to merge 1 commit into
base: main
Choose a base branch
from
+88 −20
Draft

feat: build host-only doc tools in host config via aspect_bazel_lib platform_transition_binary #635

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions MODULE.bazel
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,10 @@ use_repo(pip, "docs_as_code_hub_env")

# Additional Python rules provided by aspect, e.g. an improved version of
bazel_dep(name = "aspect_rules_py", version = "1.4.0")

# `platform_transition_binary` (used to build host-only doc tools in the host
# config under a cross `--platforms`). Already in the graph via aspect_rules_py.
Comment on lines +51 to +52

@a-zw a-zw Jul 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# `platform_transition_binary` (used to build host-only doc tools in the host
# config under a cross `--platforms`). Already in the graph via aspect_rules_py.

No need for verbosity.

bazel_dep(name = "aspect_bazel_lib", version = "2.16.0")
bazel_dep(name = "buildifier_prebuilt", version = "8.2.0.2")

# PlantUML for docs
Expand Down
104 changes: 84 additions & 20 deletions docs.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,10 +41,21 @@ Easy streamlined way for S-CORE docs-as-code.
#
# For user-facing documentation, refer to `/README.md`.

load("@aspect_bazel_lib//lib:transitions.bzl", "platform_transition_binary")
load("@aspect_rules_py//py:defs.bzl", "py_binary", "py_venv")
load("@docs_as_code_hub_env//:requirements.bzl", "all_requirements")
load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")

# -- Host-platform transition for host-only documentation tooling --------------
#
# The runnable doc targets (docs, ide_support, live_preview, ...) are pure host tools that run
# Python/Sphinx locally. Under a cross `--platforms` (e.g. QNX) they would be configured for the
# target platform and fail Python toolchain resolution. To avoid that, each is wrapped with
# `platform_transition_binary` from aspect_bazel_lib, which transitions the wrapped binary to a fixed
# `target_platform` (the autodetected host, `@local_config_platform//:host`) while forwarding its
# executable, runfiles and RunEnvironmentInfo -- so `bazel build //...` under a cross platform and
# `bazel run //:docs` both keep working.

Comment on lines +49 to +58

@a-zw a-zw Jul 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# -- Host-platform transition for host-only documentation tooling --------------
#
# The runnable doc targets (docs, ide_support, live_preview, ...) are pure host tools that run
# Python/Sphinx locally. Under a cross `--platforms` (e.g. QNX) they would be configured for the
# target platform and fail Python toolchain resolution. To avoid that, each is wrapped with
# `platform_transition_binary` from aspect_bazel_lib, which transitions the wrapped binary to a fixed
# `target_platform` (the autodetected host, `@local_config_platform//:host`) while forwarding its
# executable, runfiles and RunEnvironmentInfo -- so `bazel build //...` under a cross platform and
# `bazel run //:docs` both keep working.

This makes sense for the PR description but is too verbose for this bzl file.

def _rewrite_needs_json_to_docs_sources(labels):
"""Replace '@repo//:needs_json' -> '@repo//:docs_sources' for every item."""
out = []
Expand All @@ -63,8 +74,10 @@ def _rewrite_needs_json_to_sourcelinks(labels):
s = str(x)
if s.endswith("//:needs_json"):
out.append(s.replace("//:needs_json", "//:sourcelinks_json"))

#Items which do not end up with '//:needs_json' shall not be appended to 'out'.
#They are treated separately and are not related to source code linking.

return out

def _merge_sourcelinks(name, sourcelinks, known_good = None):
Expand Down Expand Up @@ -100,15 +113,19 @@ def _missing_requirements(deps):
"""Add Python hub dependencies if they are missing."""
found = []
missing = []

def _target_to_packagename(target):
return str(target).split("/")[-1].split(":")[0]

all_packages = [_target_to_packagename(pkg) for pkg in all_requirements]

def _find(pkg):
for dep in deps:
dep_pkg = _target_to_packagename(dep)
if dep_pkg == pkg:
return True
return False

for pkg in all_packages:
if _find(pkg):
found.append(pkg)
Expand Down Expand Up @@ -166,6 +183,11 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good =

sphinx_build_binary(
name = "sphinx_build",
# `sphinx_build` is only consumed as a tool (see `needs_json`'s `sphinx` attr below), so Bazel
# already builds it in the exec (host) config -- no host transition needed. It is tagged
# `manual` so a cross-platform `bazel build //...` doesn't configure it for the target platform
# (which would fail Python toolchain resolution).

@a-zw a-zw Jul 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment is overly specific. My understanding is that tagging as "manual" means bazel wildcards (e.g. //...) do not match it.

Documentation:

manual keyword will exclude the target from expansion of target pattern wildcards (..., :*, :all, etc.) and test_suite rules which do not list the test explicitly when computing the set of top-level targets to build/run for the build, test, and coverage commands. It does not affect target wildcard or test suite expansion in other contexts, including the query command. Note that manual does not imply that a target should not be built/run automatically by continuous build/test systems. For example, it may be desirable to exclude a target from bazel test ... because it requires specific Bazel flags, but still have it included in properly-configured presubmit or continuous test runs.

tags = ["manual"],
visibility = ["//visibility:private"],
data = data + metamodel_data,
deps = deps,
Expand Down Expand Up @@ -225,22 +247,34 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good =
docs_env["ACTION"] = "incremental"

py_binary(
name = "docs",
tags = ["cli_help=Build documentation:\nbazel run //:docs"],
name = "docs_impl",
tags = ["manual"],
srcs = [incremental_src],
data = docs_data,
deps = deps,
env = docs_env
env = docs_env,
)
platform_transition_binary(
name = "docs",
binary = ":docs_impl",
target_platform = "@local_config_platform//:host",
tags = ["cli_help=Build documentation:\nbazel run //:docs"],

@a-zw a-zw Jul 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
tags = ["cli_help=Build documentation:\nbazel run //:docs"],

This tag never made sense, so this would be a good opportunity to remove them.

)

docs_sources_env["ACTION"] = "incremental"
py_binary(
name = "docs_combo",
tags = ["cli_help=Build full documentation with all dependencies:\nbazel run //:docs_combo"],
name = "docs_combo_impl",
tags = ["manual"],
srcs = [incremental_src],
data = combo_data,
deps = deps,
env = docs_sources_env
env = docs_sources_env,
)
platform_transition_binary(
name = "docs_combo",
binary = ":docs_combo_impl",
target_platform = "@local_config_platform//:host",
tags = ["cli_help=Build full documentation with all dependencies:\nbazel run //:docs_combo"],
)

native.alias(
Expand All @@ -251,52 +285,82 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good =

docs_env["ACTION"] = "linkcheck"
py_binary(
name = "docs_link_check",
tags = ["cli_help=Verify Links inside Documentation:\nbazel run //:link_check\n (Note: this could take a long time)"],
name = "docs_link_check_impl",
tags = ["manual"],
srcs = [incremental_src],
data = docs_data,
deps = deps,
env = docs_env
env = docs_env,
)
platform_transition_binary(
name = "docs_link_check",
binary = ":docs_link_check_impl",
target_platform = "@local_config_platform//:host",
tags = ["cli_help=Verify Links inside Documentation:\nbazel run //:link_check\n (Note: this could take a long time)"],
)

docs_env["ACTION"] = "check"
py_binary(
name = "docs_check",
tags = ["cli_help=Verify documentation:\nbazel run //:docs_check"],
name = "docs_check_impl",
tags = ["manual"],
srcs = [incremental_src],
data = docs_data,
deps = deps,
env = docs_env
env = docs_env,
)
platform_transition_binary(
name = "docs_check",
binary = ":docs_check_impl",
target_platform = "@local_config_platform//:host",
tags = ["cli_help=Verify documentation:\nbazel run //:docs_check"],
)

docs_env["ACTION"] = "live_preview"
py_binary(
name = "live_preview",
tags = ["cli_help=Live preview documentation in the browser:\nbazel run //:live_preview"],
name = "live_preview_impl",
tags = ["manual"],
srcs = [incremental_src],
data = docs_data,
deps = deps,
env = docs_env
env = docs_env,
)
platform_transition_binary(
name = "live_preview",
binary = ":live_preview_impl",
target_platform = "@local_config_platform//:host",
tags = ["cli_help=Live preview documentation in the browser:\nbazel run //:live_preview"],
)

docs_sources_env["ACTION"] = "live_preview"
py_binary(
name = "live_preview_combo_experimental",
tags = ["cli_help=Live preview full documentation with all dependencies in the browser:\nbazel run //:live_preview_combo_experimental"],
name = "live_preview_combo_experimental_impl",
tags = ["manual"],
srcs = [incremental_src],
data = combo_data,
deps = deps,
env = docs_sources_env
env = docs_sources_env,
)
platform_transition_binary(
name = "live_preview_combo_experimental",
binary = ":live_preview_combo_experimental_impl",
target_platform = "@local_config_platform//:host",
tags = ["cli_help=Live preview full documentation with all dependencies in the browser:\nbazel run //:live_preview_combo_experimental"],
)

py_venv(
name = "ide_support",
tags = ["cli_help=Create virtual environment (.venv_docs) for documentation support:\nbazel run //:ide_support"],
name = "ide_support_impl",
tags = ["manual"],
venv_name = ".venv_docs",
deps = deps,
data = data,
package_collisions = "warning",
)
platform_transition_binary(
name = "ide_support",
binary = ":ide_support_impl",
target_platform = "@local_config_platform//:host",
tags = ["cli_help=Create virtual environment (.venv_docs) for documentation support:\nbazel run //:ide_support"],
)

sphinx_docs(
name = "needs_json",
Expand Down
Loading