docs: make //docs:man_pages hermetic by managing pandoc via Bazel#10764
docs: make //docs:man_pages hermetic by managing pandoc via Bazel#10764luarss wants to merge 5 commits into
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request replaces the host-dependent make and nroff workflow for generating man pages with a hermetic Bazel rule. It downloads pre-built platform-specific pandoc binaries and orchestrates the generation using a new Python driver script (manpages_impl.py). The review feedback highlights two important issues in the new Python script: first, pandoc needs an explicit -f man format specification when reading generated roff files to prevent them from being parsed as markdown; second, the script should preserve and append to the existing PYTHONPATH instead of overwriting it entirely, which could break Bazel's Python runtime environment.
|
Comments fixed in 0fe6274 |
|
@codex review |
|
merge conflict to resolve |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e93462a383
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") | ||
|
|
||
| http_archive( |
There was a problem hiding this comment.
Adding these root-module http_archive repos changes Bzlmod state, but MODULE.bazel.lock was not updated (it has no pandoc_* repo specs). The PR CI workflow .github/workflows/github-actions-check-bazel-lock.yml runs bazelisk mod deps --lockfile_mode=error; Bazel's CLI reference describes error mode as using the lockfile but throwing if it is not up to date, so this will fail before //docs:man_pages is built. Please run bazelisk mod deps --lockfile_mode=update and commit the lockfile.
Useful? React with 👍 / 👎.
The previous rule called make, pandoc, nroff, and col via the host PATH with use_default_shell_env=True and no-sandbox=1, breaking hermetic and remote-execution builds (issue The-OpenROAD-Project#10692). Changes: - MODULE.bazel: add http_archive downloads of pandoc 3.10 pre-built binaries for Linux amd64/arm64 and macOS x86_64/arm64 (pandoc is not on BCR yet). - bazel/BUILD: add config_setting per platform, a filegroup that selects the right pandoc binary, and a py_binary driver. - bazel/manpages_impl.py: new Python driver that replaces make + link_readmes.sh + nroff/col. All inputs arrive as explicit CLI args; pandoc --to=plain replaces nroff -man | col -b. - bazel/man_pages.bzl: rewrite to use ctx.actions.run with declared tool inputs; removes use_default_shell_env and no-sandbox. - docs/BUILD.bazel: drop Makefile and link_readmes.sh from inputs. Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
Add //docs:man_pages_build_test to catch regressions in the hermetic man page build. Remove the now-dead bazel-manpages Makefile target which was previously called by Bazel but is no longer needed since manpages_impl.py drives the build directly. Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
- Add docstrings to _run_pandoc, _process_section, and main() - Document skip_stems parameter in _process_section - Clarify messages.txt copy comment - Fix capitalization in man_pages.bzl module docstring (html → HTML) Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
e93462a to
34b2e9c
Compare
Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
2 participants
The previous rule called make, pandoc, nroff, and col via the host PATH with use_default_shell_env=True and no-sandbox=1, breaking hermetic and remote-execution builds (issue #10692).
Summary
MODULE.bazel: download pandoc 3.10 pre-built binaries for Linux amd64/arm64 and macOS x86_64/arm64 viahttp_archive(pandoc is not on BCR).bazel/BUILD: addconfig_settingper platform, afilegroupthat selects the correct pandoc binary at build time, and apy_binarydrivertarget.
bazel/manpages_impl.py: new Python driver replacingmake+link_readmes.sh+nroff/col. All inputs (pandoc binary, README files, messages,scripts) arrive as explicit CLI arguments;
pandoc --to=plainreplacesnroff -man | col -bfor cat pages.bazel/man_pages.bzl: rewritten to usectx.actions.runwith declared tool inputs; removesuse_default_shell_envandno-sandbox.docs/BUILD.bazel: dropMakefileandlink_readmes.shfrom inputs; add//docs:man_pages_build_testto catch regressions.docs/Makefile: remove deadbazel-manpagestarget (no longer called by Bazel).Type of Change
Impact
[How does this change the tool's behavior?]
Verification
./etc/Build.sh).Related Issues
fixes #10692