bazel: build and package man pages as runfiles

BUILD.bazel

@@ -180,6 +180,9 @@ cc_binary(
         "src/Main.cc",
     ],
     copts = OPENROAD_COPTS,
+    data = [
+        "//docs:man_pages",
+    ],
     features = ["-use_header_modules"],
     malloc = select({
         "@platforms//os:linux": "@tcmalloc//tcmalloc",

bazel/man_pages.bzl

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2026, The OpenROAD Authors
+
+"""Bazel rule to generate man pages (cat/ and html/) from module READMEs.
+
+Runs the existing docs Makefile to produce cat/ and html/ outputs.
+Requires pandoc, nroff, and python3 (>= 3.10) on the system.
+"""
+
+def _man_pages_impl(ctx):
+    cat_dir = ctx.actions.declare_directory("cat")
+    html_dir = ctx.actions.declare_directory("html")
+
+    command = """
+set -euo pipefail
+
+# Ensure homebrew tools (pandoc, python3 >= 3.10) are available on macOS
+if [ -d /opt/homebrew/bin ]; then
+    export PATH="/opt/homebrew/bin:$PATH"
+elif [ -d /usr/local/bin ]; then
+    export PATH="/usr/local/bin:$PATH"
+fi
+
+cd docs
+
+# Symlink module READMEs into md/man2/
+bash src/scripts/link_readmes.sh 2>/dev/null || true
+
+# Run preprocessing
+python3 src/scripts/md_roff_compat.py
+
+# Generate cat and html pages via Makefile
+make -f Makefile cat web
+
+cd ..
+
+# Copy outputs to declared Bazel directories
+cp -r docs/cat/* {cat_out}/
+cp -r docs/html/* {html_out}/
+""".format(
+        cat_out = cat_dir.path,
+        html_out = html_dir.path,
+    )
+
+    ctx.actions.run_shell(
+        outputs = [cat_dir, html_dir],
+        inputs = ctx.files.docs_srcs + ctx.files.scripts + ctx.files.readmes + ctx.files.messages,
+        command = command,
+        mnemonic = "ManPages",
+        progress_message = "Generating man pages (cat + html)",
+        use_default_shell_env = True,
+    )
+
+    return [DefaultInfo(
+        files = depset([cat_dir, html_dir]),
+        runfiles = ctx.runfiles(files = [cat_dir, html_dir]),
+    )]
+
+man_pages = rule(
+    implementation = _man_pages_impl,
+    attrs = {
+        "docs_srcs": attr.label_list(
+            doc = "All source files under docs/ needed by the Makefile.",
+            allow_files = True,
+        ),
+        "messages": attr.label_list(
+            doc = "Module messages.txt files needed for man3 page generation.",
+            allow_files = [".txt"],
+        ),
+        "readmes": attr.label_list(
+            doc = "Module README.md files (src/*/README.md).",
+            allow_files = [".md"],
+        ),
+        "scripts": attr.label_list(
+            doc = "Python/shell scripts for man page generation.",
+            allow_files = True,
+        ),
+    },
+)

docs/BUILD.bazel

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2026, The OpenROAD Authors
+
+load("//bazel:man_pages.bzl", "man_pages")
+
+man_pages(
+    name = "man_pages",
+    docs_srcs = [
+        "Makefile",
+    ] + glob(["md/**/*.md"]),
+    messages = [
+        "//src/ant:messages_txt",
+        "//src/cts:messages_txt",
+        "//src/dbSta:messages_txt",
+        "//src/dft:messages_txt",
+        "//src/dpl:messages_txt",
+        "//src/drt:messages_txt",
+        "//src/dst:messages_txt",
+        "//src/fin:messages_txt",
+        "//src/gpl:messages_txt",
+        "//src/grt:messages_txt",
+        "//src/ifp:messages_txt",
+        "//src/mpl:messages_txt",
+        "//src/odb:messages_txt",
+        "//src/pad:messages_txt",
+        "//src/par:messages_txt",
+        "//src/pdn:messages_txt",
+        "//src/ppl:messages_txt",
+        "//src/psm:messages_txt",
+        "//src/rcx:messages_txt",
+        "//src/rmp:messages_txt",
+        "//src/rsz:messages_txt",
+        "//src/stt:messages_txt",
+        "//src/tap:messages_txt",
+        "//src/upf:messages_txt",
+        "//src/utl:messages_txt",
+    ],
+    readmes = [
+        "//src/ant:README.md",
+        "//src/cts:README.md",
+        "//src/dft:README.md",
+        "//src/dpl:README.md",
+        "//src/drt:README.md",
+        "//src/fin:README.md",
+        "//src/gpl:README.md",
+        "//src/grt:README.md",
+        "//src/gui:README.md",
+        "//src/ifp:README.md",
+        "//src/mpl:README.md",
+        "//src/odb:README.md",
+        "//src/pad:README.md",
+        "//src/par:README.md",
+        "//src/pdn:README.md",
+        "//src/ppl:README.md",
+        "//src/psm:README.md",
+        "//src/rcx:README.md",
+        "//src/rmp:README.md",
+        "//src/rsz:README.md",
+        "//src/stt:README.md",
+        "//src/tap:README.md",
+        "//src/upf:README.md",
+        "//src/utl:README.md",
+    ],
+    scripts = [
+        "//docs/src/scripts:link_readmes.sh",
+        "//docs/src/scripts:md_roff_compat.py",
+        "//docs/src/scripts:manpage.py",
+        "//docs/src/scripts:extract_utils.py",
+    ],
+    visibility = ["//visibility:public"],
+)

docs/src/scripts/BUILD

@@ -15,3 +15,10 @@ py_test(
     srcs = ["test_extract_utils.py"],
     deps = [":extract_utils"],
 )
+
+exports_files([
+    "md_roff_compat.py",
+    "manpage.py",
+    "link_readmes.sh",
+    "extract_utils.py",
+])

src/OpenRoad.cc

@@ -710,6 +710,13 @@ std::string OpenRoad::getDocsPath() const
     return "";
   }
 
+  // Check Bazel runfiles layout first
+  const std::filesystem::path runfiles_docs
+      = std::filesystem::path(exe + ".runfiles") / "_main" / "docs";
+  if (std::filesystem::exists(runfiles_docs)) {
+    return runfiles_docs;
+  }
+
   std::filesystem::path path(exe);
 
   // remove binary name

src/ant/BUILD

@@ -115,5 +115,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/ant/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/ant/test:__pkg__",
+    ],
 )

src/cts/BUILD

@@ -151,5 +151,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/cts/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/cts/test:__pkg__",
+    ],
 )

src/dbSta/BUILD

@@ -4,6 +4,7 @@
 load("@rules_cc//cc:cc_library.bzl", "cc_library")
 load("//bazel:tcl_encode_or.bzl", "tcl_encode")
 load("//bazel:tcl_wrap_cc.bzl", "tcl_wrap_cc")
+load("//test:regression.bzl", "messages_txt")
 
 package(
     default_visibility = ["//:__subpackages__"],
@@ -195,3 +196,7 @@ tcl_wrap_cc(
         "//src/odb:swig",
     ],
 )
+
+messages_txt(
+    visibility = ["//docs:__pkg__"],
+)

src/dft/BUILD

@@ -105,5 +105,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/dft/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/dft/test:__pkg__",
+    ],
 )

src/dft/test/BUILD

@@ -1,11 +1,11 @@
-load("@rules_python//python:defs.bzl", "py_test")
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright (c) 2022-2025, The OpenROAD Authors
 
 # Test Parity Note: All tests from CMakeLists.txt are included in this BUILD file.
 # No tests are intentionally excluded. See .kiro/specs/bazel-cmake-test-parity/intentional_exclusions.md
 
 load("@rules_cc//cc:cc_test.bzl", "cc_test")
+load("@rules_python//python:defs.bzl", "py_test")
 load("//test:regression.bzl", "doc_check_test", "regression_test")
 
 package(features = ["layering_check"])

src/dpl/BUILD

@@ -193,5 +193,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/dpl/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/dpl/test:__pkg__",
+    ],
 )

src/drt/BUILD

@@ -324,5 +324,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/drt/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/drt/test:__pkg__",
+    ],
 )

src/dst/BUILD

@@ -4,6 +4,7 @@
 load("@rules_cc//cc:cc_library.bzl", "cc_library")
 load("//bazel:tcl_encode_or.bzl", "tcl_encode")
 load("//bazel:tcl_wrap_cc.bzl", "tcl_wrap_cc")
+load("//test:regression.bzl", "messages_txt")
 
 package(
     default_visibility = ["//:__subpackages__"],
@@ -99,3 +100,7 @@ tcl_wrap_cc(
         "//src/odb:swig",
     ],
 )
+
+messages_txt(
+    visibility = ["//docs:__pkg__"],
+)

src/fin/BUILD

@@ -98,5 +98,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/fin/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/fin/test:__pkg__",
+    ],
 )

src/gpl/BUILD

@@ -176,5 +176,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/gpl/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/gpl/test:__pkg__",
+    ],
 )

src/grt/BUILD

@@ -268,5 +268,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/grt/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/grt/test:__pkg__",
+    ],
 )

src/ifp/BUILD

@@ -114,5 +114,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/ifp/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/ifp/test:__pkg__",
+    ],
 )

src/mpl/BUILD

@@ -134,5 +134,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/mpl/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/mpl/test:__pkg__",
+    ],
 )

src/mpl/test/BUILD

@@ -1,11 +1,11 @@
-load("@rules_python//python:defs.bzl", "py_test")
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright (c) 2022-2025, The OpenROAD Authors
 
 # Test Parity Note: All tests from CMakeLists.txt are included in this BUILD file.
 # No tests are intentionally excluded. See .kiro/specs/bazel-cmake-test-parity/intentional_exclusions.md
 
 load("@rules_cc//cc:cc_test.bzl", "cc_test")
+load("@rules_python//python:defs.bzl", "py_test")
 load("//test:regression.bzl", "doc_check_test", "regression_test")
 
 package(features = ["layering_check"])

src/odb/BUILD

@@ -166,5 +166,8 @@ messages_txt(
     src_patterns = [
         "include/odb/*.h",
     ],
-    visibility = ["//src/odb/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/odb/test:__pkg__",
+    ],
 )

src/pad/BUILD

@@ -86,5 +86,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/pad/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/pad/test:__pkg__",
+    ],
 )

src/par/BUILD

@@ -162,5 +162,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/par/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/par/test:__pkg__",
+    ],
 )

src/pdn/BUILD

@@ -121,5 +121,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/pdn/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/pdn/test:__pkg__",
+    ],
 )

src/ppl/BUILD

@@ -126,5 +126,8 @@ filegroup(
 )
 
 messages_txt(
-    visibility = ["//src/ppl/test:__pkg__"],
+    visibility = [
+        "//docs:__pkg__",
+        "//src/ppl/test:__pkg__",
+    ],
 )