wehub-resource-sync
85 lines
4.1 KiB
YAML
85 lines
4.1 KiB
YAML
# .readthedocs.yaml
|
|
# Read the Docs configuration file
|
|
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
|
|
|
|
# Required
|
|
version: 2
|
|
|
|
# Set the version of Python and other tools you might need
|
|
build:
|
|
os: ubuntu-24.04
|
|
tools:
|
|
python: "3.11"
|
|
jobs:
|
|
# On PR builds, skip the Sphinx build when the PR doesn't touch any
|
|
# files that affect documentation output. Reduces queue pressure on
|
|
# the shared RTD build slots when several PRs are open at once.
|
|
# Tag/branch builds (master, stable, etc.) always run.
|
|
# The guard matches doc/ but excludes doc/.claude/ (Claude Code skills
|
|
# and agent files), which never participate in the Sphinx build, so a
|
|
# PR that changes only those paths skips the build instead of running one.
|
|
# Code sources (python/ray/, rllib/) are intentionally not matched, so a
|
|
# code-only PR skips this PR preview. The RTD PR check is not a required
|
|
# merge gate, and the post-merge master build and the Buildkite doc_build
|
|
# still render docstring-driven API-reference changes. This trades a
|
|
# non-gating premerge preview for less pressure on the shared RTD slots.
|
|
# See https://docs.readthedocs.com/platform/stable/guides/build/skip-build.html
|
|
#
|
|
# Some constructs are avoided deliberately because RTD's job runner
|
|
# silently drops scripts that contain them: use echo (not printf
|
|
# with a backslash-escape format string), avoid backslash escapes
|
|
# in general, and keep shell comments out of this block so that
|
|
# backticks/$() inside comments don't confuse the preprocessor.
|
|
# The runner also strips the surrounding single quotes from arguments,
|
|
# so use git's :! exclude shorthand rather than :(exclude): unquoted
|
|
# parentheses reach /bin/sh (dash) and abort the script with a syntax error.
|
|
post_checkout:
|
|
- |
|
|
if [ "${READTHEDOCS_VERSION_TYPE:-}" != "external" ]; then
|
|
echo "Not a PR build (version type: '${READTHEDOCS_VERSION_TYPE:-unset}'); building docs."
|
|
exit 0
|
|
fi
|
|
git fetch --depth=500 origin master 2>/dev/null || true
|
|
if ! git merge-base origin/master HEAD >/dev/null 2>&1; then
|
|
echo "Could not determine merge-base with origin/master; building docs to be safe."
|
|
exit 0
|
|
fi
|
|
if git diff --quiet origin/master...HEAD -- doc/ ':!doc/.claude/' .readthedocs.yaml; then
|
|
echo "No doc-affecting files changed in this PR; skipping Sphinx build."
|
|
echo "Files changed in PR:"
|
|
git diff --name-only origin/master...HEAD
|
|
exit 183
|
|
fi
|
|
echo "Doc-affecting files changed; building docs. Changed doc-relevant paths:"
|
|
git diff --name-only origin/master...HEAD -- doc/ ':!doc/.claude/' .readthedocs.yaml
|
|
# Override the html build step so every build runs a full clean Sphinx
|
|
# build via the doc/Makefile html target, for PR (external) previews and
|
|
# branch/tag builds alike.
|
|
#
|
|
# The incremental-from-master-cache path added in #64277 is disabled for
|
|
# now. On every PR preview Sphinx discards the restored cache because a
|
|
# config value differs between the environment that produced the cache and
|
|
# the RTD build environment, so it rebuilds all documents anyway while
|
|
# still paying the cache download and extract cost, and it risks a second
|
|
# clean rebuild when the incremental leg trips a warning. A clean build is
|
|
# faster and lower-variance in practice today. Re-enable the incremental
|
|
# path only once cache reuse is confirmed (Sphinx logs "N changed" rather
|
|
# than "NNNN added") and stale-artifact pruning lands for PRs that rename
|
|
# or delete sources. The rtd and rtd-fallback Makefile targets and
|
|
# doc/load_doc_cache.py stay in the tree for that re-enable.
|
|
build:
|
|
html:
|
|
- |
|
|
make -C doc html HTMLDIR="$READTHEDOCS_OUTPUT/html"
|
|
|
|
# Build documentation in the docs/ directory with Sphinx
|
|
sphinx:
|
|
configuration: doc/source/conf.py
|
|
fail_on_warning: true
|
|
|
|
# We recommend specifying your dependencies to enable reproducible builds:
|
|
# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
|
|
python:
|
|
install:
|
|
- requirements: doc/requirements-doc.lock.txt
|