Skip to content

docs: add bazel sphinx_build_test replicating ReadTheDocs CI (salvage #10695) - #11068

Open
oharboe wants to merge 7 commits into
The-OpenROAD-Project:masterfrom
oharboe:salvage-10695
Open

docs: add bazel sphinx_build_test replicating ReadTheDocs CI (salvage #10695)#11068
oharboe wants to merge 7 commits into
The-OpenROAD-Project:masterfrom
oharboe:salvage-10695

Conversation

@oharboe

@oharboe oharboe commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

Summary

Salvage of #10695 / #10184 (merged with current master to preserve review history and fixed workspace isolation).

Adds a hermetic Bazel py_test target (//docs:sphinx_build_test) that runs the same Sphinx documentation build performed by readthedocs.org/openroad, catching broken cross-references, malformed markup, missing files, and toc.yml issues locally before they reach CI.

  • //docs:sphinx_build_test runs sphinx-build -b html with pinned Python deps from @openroad-pip (no system Sphinx required).
  • Tagged doc_check for filtering: bazelisk test --test_tag_filters=doc_check //docs/....

Changes from #10695 / #10184

  • Preserved History: Merged origin/master into salvage-10695 keeping all commit and review history intact.
  • Fixed Workspace Isolation (Review Finding): Updated docs/sphinx_build_test.py to copy docs/ and root README.md into an isolated tempfile.mkdtemp() directory before running Sphinx. This guarantees no workspace files are mutated in place and leaves no dirty git state if interrupted.
  • Dependencies: Added sphinx-llm requirement (added to docs/conf.py in docs: dynamically generate llms.txt and llms-full.txt #10598) and updated bazel/requirements_lock_3_13.txt.

Fixes #9885
CC: @luarss @alokkumardalei-wq

Verification

  • bazelisk test //docs:sphinx_build_test passes locally
  • git status verified clean post-execution
  • Signed commits (DCO)

alokkumardalei-wq and others added 5 commits June 20, 2026 04:11
Adds a hermetic Bazel `py_test` target that runs the same Sphinx
documentation build performed by readthedocs.org/openroad, catching
broken cross-references, malformed markup, missing files, and toc.yml
issues locally before they reach CI.

- `//docs:sphinx_build_test` runs `sphinx-build -b html` with pinned
  Python deps from `@openroad-pip` (no system Sphinx required).
- Tagged `doc_check` for filtering: `bazelisk test --test_tag_filters=doc_check //docs/...`.
- Mirrors conf.py setup (main symlink, README2.md prefix swap, messages
  glossary generation, doxygen stub) and strips `bazel-*` symlinks to
  prevent recursive scanning.

Fixes The-OpenROAD-Project#9885

Signed-off-by: alokkumardalei-wq <alokkumardalei2@gmail.com>
Simplify the test per @luarss's review (#4148341864):

- Pin Sphinx deps with `==` in bazel/requirements.in and clarify
  the Python 3.13 target; regenerated lock file is unchanged.
- Drop "main/bazel-*" from conf.py exclude_patterns (scope creep
  for this PR; defensive only for local-dev sphinx-build from a
  workspace that has been bazel-built).
- Replace _find_docs_dir() helper with a DOCS_DIR module constant.
- Stop mirroring conf.py's setup() in the test. Stage //:README.md
  in runfiles and rely on Sphinx to call conf.py's setup(app)
  directly; revert-links.py is still invoked post-build to undo
  the in-place swap_prefix mutations on README.md / README2.md.

Verified locally:
  bazelisk test //docs:sphinx_build_test
  //docs:sphinx_build_test PASSED in 2.8s

Signed-off-by: alokkumardalei-wq <alokkumardalei2@gmail.com>
Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
…n tempdir

Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
@oharboe
oharboe requested a review from a team as a code owner August 5, 2026 06:56
@oharboe
oharboe requested a review from eder-matheus August 5, 2026 06:56
@github-actions github-actions Bot added the size/L label Aug 5, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

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.

Code Review

This pull request introduces a hermetic Bazel test (sphinx_build_test) to replicate the ReadTheDocs Sphinx documentation build locally, adding the necessary Sphinx dependencies to bazel/requirements.in and updating the lockfile. Feedback on the changes suggests pinning the sphinx-llm dependency in requirements.in for reproducibility, removing the local and no-sandbox tags from the py_test target to allow sandboxed execution and caching, cleaning up an unused subprocess import, and moving the sphinx import to the top of the test script in accordance with PEP 8.

Comment thread bazel/requirements.in Outdated
Comment thread docs/BUILD.bazel
Comment thread docs/sphinx_build_test.py
Comment thread docs/sphinx_build_test.py Outdated
oharboe added 2 commits August 5, 2026 09:01
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add bazelisk test target that does whatever testing the read the docs/readthedocs.org:openroad does

3 participants