docs: add bazel sphinx_build_test replicating ReadTheDocs CI (salvage #10695) - #11068
Open
oharboe wants to merge 7 commits into
Open
docs: add bazel sphinx_build_test replicating ReadTheDocs CI (salvage #10695)#11068oharboe wants to merge 7 commits into
oharboe wants to merge 7 commits into
Conversation
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>
Contributor
There was a problem hiding this comment.
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.
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Salvage of #10695 / #10184 (merged with current
masterto preserve review history and fixed workspace isolation).Adds a hermetic Bazel
py_testtarget (//docs:sphinx_build_test) that runs the same Sphinx documentation build performed byreadthedocs.org/openroad, catching broken cross-references, malformed markup, missing files, andtoc.ymlissues locally before they reach CI.//docs:sphinx_build_testrunssphinx-build -b htmlwith pinned Python deps from@openroad-pip(no system Sphinx required).doc_checkfor filtering:bazelisk test --test_tag_filters=doc_check //docs/....Changes from #10695 / #10184
origin/masterintosalvage-10695keeping all commit and review history intact.docs/sphinx_build_test.pyto copydocs/and rootREADME.mdinto an isolatedtempfile.mkdtemp()directory before running Sphinx. This guarantees no workspace files are mutated in place and leaves no dirty git state if interrupted.sphinx-llmrequirement (added todocs/conf.pyin docs: dynamically generate llms.txt and llms-full.txt #10598) and updatedbazel/requirements_lock_3_13.txt.Fixes #9885
CC: @luarss @alokkumardalei-wq
Verification
bazelisk test //docs:sphinx_build_testpasses locallygit statusverified clean post-execution