docs: don't abort the docs build when BUILD_PREVIEW/BUILD_LATEST is set but empty

[LeSingh1]

Problem

Both Sphinx configs read the two docs-build flags with a bare int():

# cuda_core/docs/source/conf.py  (6 call sites)
# cuda_python/docs/source/conf.py (4 call sites)
if int(os.environ.get("BUILD_PREVIEW", 0)):
    ...

os.environ.get(name, default) returns the empty string, not the default, when a variable is exported but empty. And the build scripts that drive these configs already treat that state as "not set":

# cuda_core/docs/build_docs.sh:27, cuda_python/docs/build_docs.sh:28
if [[ "${LATEST_ONLY}" == "1" && -z "${BUILD_PREVIEW:-}" && -z "${BUILD_LATEST:-}" ]]; then
    export BUILD_LATEST=1
fi

-z is explicit: empty means unset. Then conf.py disagrees and raises:

$ BUILD_PREVIEW= ./build_docs.sh latest-only
  File ".../docs/source/conf.py", line 33, in _github_examples_ref
    if int(os.environ.get("BUILD_PREVIEW", 0)) or int(os.environ.get("BUILD_LATEST", 0)):
ValueError: invalid literal for int() with base 10: ''

That kills the docs build from inside conf.py, before any page is rendered. Measured against the exact expression on main:

BUILD_PREVIEW	result on main
unset	False
"1"	True
"0"	False
""	ValueError
" "	ValueError
"true"	ValueError

BUILD_PREVIEW / BUILD_LATEST are set to "1" by .github/actions/get_pr_number, so CI does not hit this today — it bites anyone driving the scripts by hand or from a wrapper that exports the variable unconditionally, which is precisely the case build_docs.sh wrote a -z test for.

Fix

Add an _env_flag helper to each config and route all ten call sites through it. Unset, empty, whitespace-only and "0" are false; any other value is true, so BUILD_LATEST=true is honoured rather than aborting the build. Integer values keep their exact current meaning.

The helper is duplicated across the two configs deliberately — they already duplicate _html_baseurl between them, and a shared module would mean restructuring cuda_python/docs/exts/, which is more churn than this warrants.

Verification

conf.py has no test home in this repo (nothing imports or exercises either file outside a Sphinx run), so this ships without a unit test — I want to be explicit about that rather than invent a contrived one. What I did verify:

• Extracted _env_flag from each committed config via AST and exercised it directly, then reverted both files to upstream/main and ran the same probe against the original expression:

--- WITH FIX (HEAD) ---
  cuda_core    ''->False  '  '->False  'true'->True
  cuda_python  ''->False  '  '->False  'true'->True
--- upstream/main ---
  cuda_core    ''->ValueError  '  '->ValueError  'true'->ValueError
  cuda_python  ''->ValueError  '  '->ValueError  'true'->ValueError

• ruff check / ruff format --check and python -m py_compile clean on both files.
• The revert/restore ran commit-first: the fix was committed, the files reverted from upstream/main for the probe, then restored with git restore --source=HEAD --worktree, wrapped in try/finally. git diff --cached and git diff both empty afterwards.

If you would rather have this as a shared helper under cuda_python/docs/exts/ with a test, say the word and I will restructure it.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.