ray/.readthedocs.yaml at master · Point72/ray · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
# .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. On PR (external) builds, build incrementally
    # from the latest master doc cache, falling back to a clean build
    # (rtd-fallback) if it fails. PRs that delete or move doc sources skip the
    # incremental path: the restored cache can't prune the stale pages/stubs they
    # leave behind, and a clean rename wouldn't trip a warning to force the
    # fallback. The prune-on-restore fix is tracked in DOC-1314. Branch/tag builds
    # (master, stable, release tags) always do a full clean build so published
    # output is never stale. Targets live in doc/Makefile (rtd, rtd-fallback, html).
    build:
      html:
        - |
          if [ "${READTHEDOCS_VERSION_TYPE:-}" = "external" ]; then
            if ! git diff --quiet --no-renames --diff-filter=D origin/master...HEAD -- doc/source/ 2>/dev/null; then
              echo "PR deletes or moves doc sources; the incremental cache cannot prune their stale pages, so building clean (DOC-1314)."
              make -C doc rtd-fallback HTMLDIR="$READTHEDOCS_OUTPUT/html"
            else
              echo "PR build; attempting incremental build from the master doc cache."
              make -C doc rtd HTMLDIR="$READTHEDOCS_OUTPUT/html" || make -C doc rtd-fallback HTMLDIR="$READTHEDOCS_OUTPUT/html"
            fi
          else
            echo "Branch/tag build; running a full clean build."
            make -C doc html HTMLDIR="$READTHEDOCS_OUTPUT/html"
          fi

# 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