Added hermetic Graphviz support for Sphinx

Optimize conf template path/env resolution

Author: AAmbuj

MODULE.bazel

@@ -34,6 +34,11 @@ bazel_dep(name = "bazel_skylib", version = "1.7.1")
 bazel_dep(name = "buildifier_prebuilt", version = "8.2.0.2")
 bazel_dep(name = "flatbuffers", version = "25.9.23")
 bazel_dep(name = "download_utils", version = "1.2.2")
+git_override(
+    module_name = "download_utils",
+    commit = "3b96912fb6622dda83f25efd1f8ae596fc4a63a6",
+    remote = "https://gitlab.arm.com/bazel/download_utils.git",
+)
 
 # flatbuffers depends on this transitively, but older grpc-java version
 # The main problem is that there the command `bazel mod deps` is broken, which
@@ -254,6 +259,19 @@ deb(
     urls = ["https://archive.ubuntu.com/ubuntu/pool/universe/l/lcov/lcov_2.0-4ubuntu2_all.deb"],
 )
 
+###############################################################################
+# Graphviz deb package (cmake release; bundles all graphviz .so files so
+# dot_builtins runs without system graphviz installation)
+# Uses download_deb from @download_utils at a commit that includes
+# data.tar.gz support in download/deb/repository.bzl.
+###############################################################################
+deb(
+    name = "graphviz_deb",
+    build = "//third_party/graphviz:graphviz.BUILD",
+    integrity = "sha256-Jk5gSqo8l0INoY+kr1ZAsi2WhZY8LlAFlEag54H3Q2Q=",
+    urls = ["https://gitlab.com/api/v4/projects/4207231/packages/generic/graphviz-releases/12.2.1/ubuntu_24.04_graphviz-12.2.1-cmake.deb"],
+)
+
 register_toolchains(
     "//bazel/rules/rules_score:sphinx_default_toolchain",
 )

bazel/rules/rules_score/private/sphinx_module.bzl

@@ -236,10 +236,35 @@ def _score_html_impl(ctx):
         "--log-level",
         get_log_level(ctx),
     ]
+
+    # Wire in the hermetic graphviz deb (dot_builtins + bundled shared libs).
+    # conf.template.py resolves all three env vars (GRAPHVIZ_DOT,
+    # LD_LIBRARY_PATH, LTDL_LIBRARY_PATH) from execroot-relative to absolute
+    # paths so dot_builtins can load its plugins without a system installation.
+    _dot_suffix = "/usr/bin/dot_builtins"
+    graphviz_files = ctx.files.graphviz
+    dot_binary = None
+    for f in graphviz_files:
+        if f.path.endswith(_dot_suffix):
+            dot_binary = f
+            break
+    if not dot_binary:
+        fail("graphviz target {} must provide usr/bin/dot_builtins".format(ctx.attr.graphviz.label))
+
+    graphviz_prefix = dot_binary.path[:-len(_dot_suffix)]
+    graphviz_env = {
+        "GRAPHVIZ_DOT": dot_binary.path,
+        "LD_LIBRARY_PATH": graphviz_prefix + "/usr/lib",
+        "LTDL_LIBRARY_PATH": graphviz_prefix + "/usr/lib/graphviz",
+    }
+    html_inputs = html_inputs + graphviz_files
+
     ctx.actions.run(
         inputs = html_inputs,
         outputs = [sphinx_html_output],
         arguments = html_args + [args],
+        env = graphviz_env,
+        use_default_shell_env = True,
         progress_message = "Building HTML: %s" % ctx.label.name,
         executable = sphinx_toolchain.sphinx.files_to_run.executable,
         tools = [
@@ -331,6 +356,12 @@ _score_html = rule(
                   "destination paths relative to the Sphinx source root. Exactly one " +
                   "file per label. Mirrors sphinx_docs.renamed_srcs from rules_python.",
         ),
+        graphviz = attr.label(
+            default = Label("@graphviz_deb//:all"),
+            allow_files = True,
+            doc = "Graphviz cmake-release deb files (dot_builtins binary + bundled libs). " +
+                  "Provides a hermetic 'dot' binary without requiring a system graphviz installation.",
+        ),
     ),
     toolchains = ["//bazel/rules/rules_score:toolchain_type"],
 )

bazel/rules/rules_score/templates/conf.template.py

@@ -20,6 +20,7 @@
 
 import json
 import os
+import shutil as _shutil
 import sys
 from pathlib import Path
 from typing import Any, Dict, List
@@ -30,6 +31,48 @@
 # Create a logger with the Sphinx namespace
 logger = logging.getLogger(__name__)
 
+# ---------------------------------------------------------------------------
+# Helpers: Bazel execroot path resolution
+# ---------------------------------------------------------------------------
+
+
+def _bazel_execroot() -> Path:
+    """Return the Bazel execroot directory inferred from this config file's path.
+
+    conf.py is generated into ``bazel-out/…/bin/…/conf.py``, so splitting on
+    ``/bazel-out/`` gives us the execroot prefix reliably.  Falls back to the
+    current working directory when the path pattern is not recognised (e.g.
+    during unit tests or IDE runs outside Bazel).
+    """
+    parts = str(Path(__file__).resolve()).split("/bazel-out/", 1)
+    return Path(parts[0]) if len(parts) == 2 else Path.cwd()
+
+
+# Computed once at import time so _resolve_execroot_path() doesn't repeat the
+# filesystem resolution on every call.
+_EXECROOT = _bazel_execroot()
+
+
+def _resolve_execroot_path(path_value: str) -> str:
+    """Resolve an execroot-relative path to an absolute filesystem path.
+
+    Bazel passes action inputs as paths relative to the execroot (e.g.
+    ``external/+_repo_rules2+graphviz_deb/usr/bin/dot_builtins``).  Those
+    paths are only valid when the process' cwd is the execroot — which is
+    not guaranteed once Sphinx changes directories during the build.
+
+    This function makes them absolute so they work regardless of cwd.
+    Absolute paths and plain command names (e.g. ``dot``) are returned
+    unchanged.
+    """
+    p = Path(path_value)
+    if p.is_absolute():
+        return str(p)
+    if path_value.startswith("external/") or path_value.startswith("bazel-out/"):
+        return str((_EXECROOT / p).resolve())
+    return path_value
+
+
 logger.debug("#" * 80)
 logger.debug("# READING CONF.PY")
 logger.debug("SYSPATH:" + str(sys.path))
@@ -55,6 +98,7 @@
     "sphinxcontrib.plantuml",
     "trlc",
     "clickable_plantuml",
+    "sphinx.ext.graphviz",
 ]
 
 # MyST parser extensions
@@ -164,9 +208,29 @@
 plantuml = f"{plantuml_path} -Playout=smetana"
 plantuml_output_format = "svg_obj"
 
-import shutil as _shutil
+# ---------------------------------------------------------------------------
+# Graphviz (sphinx.ext.graphviz)
+# ---------------------------------------------------------------------------
+# GRAPHVIZ_DOT is set by the Bazel sphinx_module rule to point at the hermetic
+# dot_builtins binary from @graphviz_deb.  The path is execroot-relative, so
+# we resolve it to an absolute path here so it remains valid after any cwd
+# change that Sphinx may perform during the build.
+graphviz_dot = _resolve_execroot_path(
+    os.environ.get("GRAPHVIZ_DOT") or _shutil.which("dot") or "dot"
+)
 
-graphviz_dot = os.environ.get("GRAPHVIZ_DOT") or _shutil.which("dot") or "dot"
+# LD_LIBRARY_PATH and LTDL_LIBRARY_PATH are set by the Bazel rule as
+# execroot-relative paths.  We mutate os.environ (not just a local) because
+# sphinx.ext.graphviz spawns `dot` as a child process that inherits these
+# variables to locate the bundled shared libraries and plugins.  Each
+# component is resolved to absolute so it stays valid if Sphinx changes cwd
+# before spawning the dot subprocess.
+for _env_var in ("LD_LIBRARY_PATH", "LTDL_LIBRARY_PATH"):
+    _env_val = os.environ.get(_env_var, "")
+    if _env_val:
+        os.environ[_env_var] = ":".join(
+            _resolve_execroot_path(p) for p in _env_val.split(":")
+        )
 
 # HTML theme
 html_theme = "sphinx_rtd_theme"

third_party/graphviz/BUILD

@@ -0,0 +1,16 @@
+# *******************************************************************************
+# Copyright (c) 2025 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+
+# This package hosts the BUILD file used by the @graphviz_deb external repository.
+# The download_deb rule from @download_utils extracts the Graphviz cmake
+# release .deb and uses graphviz.BUILD as its top-level BUILD file.

third_party/graphviz/graphviz.BUILD

@@ -0,0 +1,49 @@
+# *******************************************************************************
+# Copyright (c) 2025 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+
+# This BUILD file is injected into the @graphviz_deb external repository by the
+# graphviz_deb rule. It exposes dot_builtins and required bundled shared
+# libraries for Sphinx graphviz rendering in a hermetic way.
+
+package(default_visibility = ["//visibility:public"])
+
+# The actual graphviz rendering binary (not the dot wrapper/launcher).
+# Uses RUNPATH $ORIGIN/../lib to find bundled shared libraries.
+filegroup(
+    name = "dot_binary",
+    srcs = ["usr/bin/dot_builtins"],
+)
+
+# Bundled graphviz shared libraries (libgvc, libcgraph, libcdt, libpathplan, libxdot).
+# These are found automatically by dot_builtins via RUNPATH $ORIGIN/../lib.
+filegroup(
+    name = "core_libs",
+    srcs = glob(["usr/lib/*.so*"]),
+)
+
+# Graphviz plugin shared libraries (libgvplugin_core, libgvplugin_dot_layout, etc.).
+# Loaded at runtime via libltdl; requires LTDL_LIBRARY_PATH=usr/lib/graphviz.
+filegroup(
+    name = "plugin_libs",
+    srcs = glob(["usr/lib/graphviz/*.so*"]),
+)
+
+# All graphviz files needed to run dot_builtins.
+filegroup(
+    name = "all",
+    srcs = [
+        ":core_libs",
+        ":dot_binary",
+        ":plugin_libs",
+    ],
+)

tools/sphinx/BUILD

@@ -12,7 +12,6 @@
 # *******************************************************************************
 
 load("@pip_rules_score//:requirements.bzl", "requirement")
-load("@pip_tooling//:requirements.bzl", "requirement")
 load("@rules_java//java:defs.bzl", "java_binary")
 load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary")