Skip to content

docs: fail the build on fetch and splice errors in conf.py - #4835

Merged
vvbandeira merged 2 commits into
The-OpenROAD-Project:masterfrom
vvbandeira:docs-confpy-harden
Nov 16, 2026
Merged

vvbandeira merged 2 commits into
The-OpenROAD-Project:masterfrom
vvbandeira:docs-confpy-harden

Conversation

@vvbandeira

Copy link
Copy Markdown
Member

docs/conf.py downloads three files from OpenROAD master when the docs build starts.
requests.get had no status check and no timeout.
On an HTTP error, the build wrote the error page into the docs file and continued.
With no timeout, a stalled connection could block the build.
This change adds a 60 s timeout and raise_for_status(), so a failed download stops the build with an HTTP error.

setup() also splices OpenROAD text into three places, and each splice depends on a heading.
Two splices used assert, which does not run under python -O.
The GitGuide splice had no check, so a renamed upstream heading removed the ORFS forking section and the build still passed.
All three splices now raise RuntimeError with the file and the missing heading.

Test: with stubbed downloads, setup() splices the good input and raises RuntimeError for each missing heading, with and without python -O.

requests.get had no status check, so an HTTP error page was written
into the downloaded file and the build went on. Add a timeout and
raise_for_status.

The two asserts that guard the splice do not run under python -O.
Replace them with RuntimeError messages that name the missing heading.

Signed-off-by: Vitor Bandeira <vvbandeira@precisioninno.com>
If OpenROAD renames '## Creating a branch', str.replace changes
nothing. The ORFS forking section then drops out of the GitGuide, and
the build passes. Raise RuntimeError when the heading is missing.

Also correct two error messages. The Supported Operating Systems
pattern fails only when a heading is missing or out of order. The
'### Setup' heading lives in docs/index.md, not in the generated
index2.md copy.

Signed-off-by: Vitor Bandeira <vvbandeira@precisioninno.com>

@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 improves error handling in docs/conf.py by adding a timeout and status check to network requests, and by replacing assert statements with explicit RuntimeError exceptions to ensure clearer, more informative failures when expected documentation headings or patterns are missing. I have no feedback to provide.

@vvbandeira
vvbandeira merged commit 2272e78 into The-OpenROAD-Project:master Nov 16, 2026
10 of 12 checks passed
@vvbandeira
vvbandeira deleted the docs-confpy-harden branch November 16, 2026 02:27
@openroad-ci

Copy link
Copy Markdown
Member

🔍 QoR check

Metrics reflect the PR merge build — i.e. what will land on the target branch.

Commit 9db660b · Jenkins build #1 · Baseline: build · View build on dashboard

62 design(s) checked — 0 with regression(s), 0 without a comparable baseline.

⚠️ 62 design(s) were compared against an approximate baseline, not the build at this PR's merge base, so changes already on the target branch can show up as regressions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants