feat: make Mermaid support configurable and default disabled

Author: Shubhangi-Nikam26

.bazelrc

@@ -23,6 +23,8 @@ build:info --//bazel/rules/rules_score:verbosity=info
 # debug build:  complete output including debug/trace from all tools
 build:debug --//bazel/rules/rules_score:verbosity=debug
 
+# Enable Mermaid diagrams in Sphinx documentation builds
+build:mermaid --//bazel/rules/rules_score:enable_mermaid
 # Standard combined coverage (Rust + Python, no Ferrocene required)
 # Usage: bazel coverage --config=coverage <targets>
 # Then run: bazel run //coverage:combined_report

bazel/rules/rules_score/BUILD

@@ -11,7 +11,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
 
-load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
+load("@bazel_skylib//rules:common_settings.bzl", "bool_flag", "string_flag")
 load("@pip_rules_score//:requirements.bzl", "requirement")
 load("@rules_python//python:pip.bzl", "compile_pip_requirements")
 load(
@@ -200,3 +200,13 @@ string_flag(
     ],
     visibility = ["//visibility:public"],
 )
+
+# ---------------------------------------------------------------------------
+# Build setting: enable Mermaid diagrams in Sphinx documentation
+# ---------------------------------------------------------------------------
+
+bool_flag(
+    name = "enable_mermaid",
+    build_setting_default = False,
+    visibility = ["//visibility:public"],
+)

bazel/rules/rules_score/private/sphinx_module.bzl

@@ -14,6 +14,7 @@
 # Helpers
 # ======================================================================================
 load("@bazel_skylib//lib:paths.bzl", "paths")
+load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo")
 load("@rules_python//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
 load("@rules_python//sphinxdocs/private:sphinx_docs_library_info.bzl", "SphinxDocsLibraryInfo")
 load("//bazel/rules/rules_score:providers.bzl", "FilteredExecpathInfo", "SphinxIndexFileInfo", "SphinxModuleInfo", "SphinxNeedsInfo")
@@ -42,12 +43,18 @@ def _create_config_py(ctx):
     config_file = ctx.actions.declare_file(ctx.label.name + "/conf.py")
     template = sphinx_toolchain.conf_template.files.to_list()[0]
 
-    # Read template and substitute PROJECT_NAME
+    # Get the enable_mermaid flag value
+    enable_mermaid = ctx.attr._enable_mermaid[BuildSettingInfo].value
+    # Convert boolean to string representation for template
+    enable_mermaid_str = "True" if enable_mermaid else "False"
+
+    # Read template and substitute PROJECT_NAME and ENABLE_MERMAID
     ctx.actions.expand_template(
         template = template,
         output = config_file,
         substitutions = {
             "{PROJECT_NAME}": ctx.label.name.replace("_", " ").title(),
+            "{ENABLE_MERMAID}": enable_mermaid_str,
         },
     )
     return config_file
@@ -69,6 +76,10 @@ sphinx_rule_attrs = dict(
         "deps": attr.label_list(
             doc = "List of other sphinx_module targets this module depends on for intersphinx.",
         ),
+        "_enable_mermaid": attr.label(
+            default = Label("//bazel/rules/rules_score:enable_mermaid"),
+            doc = "Enable Mermaid diagrams in Sphinx documentation.",
+        ),
     },
     **VERBOSITY_ATTR
 )

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

@@ -47,17 +47,21 @@
 )
 
 # Sphinx extensions - comprehensive list for SCORE modules
+# Note: sphinxcontrib.mermaid is conditionally included based on {ENABLE_MERMAID} setting
 extensions = [
     "sphinx_module_ext",
     "sphinx_needs",
     "sphinx_design",
     "myst_parser",
-    "sphinxcontrib.mermaid",
     "sphinxcontrib.plantuml",
     "trlc",
     "clickable_plantuml",
 ]
 
+# Conditionally add mermaid extension if enabled
+if {ENABLE_MERMAID}:
+    extensions.append("sphinxcontrib.mermaid")
+print("Extensions: " + str(extensions))
 # MyST parser extensions
 myst_enable_extensions = ["colon_fence"]
 

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

@@ -30,11 +30,11 @@
 )
 
 # Sphinx extensions - comprehensive list for SCORE modules
+# Note: sphinxcontrib.mermaid is conditionally included based on {ENABLE_MERMAID} setting
 extensions = [
     "sphinx_needs",
     "sphinx_design",
     "myst_parser",
-    "sphinxcontrib.mermaid",
     "sphinxcontrib.plantuml",
     "score_plantuml",
     "score_metamodel",
@@ -43,6 +43,10 @@
     "score_layout",
 ]
 
+# Conditionally add mermaid extension if enabled
+if {ENABLE_MERMAID}:
+    extensions.append("sphinxcontrib.mermaid")
+
 # MyST parser extensions
 myst_enable_extensions = ["colon_fence"]