Doc workflow is failing due to a missing file 'Doc/sphinx-warnings.txt'

[gaogaotiantian]

Bug report

Bug description:

Example: https://github.com/python/cpython/actions/runs/8883326110/job/24389960128?pr=118368

Traceback (most recent call last):
  File "/home/runner/work/cpython/cpython/Doc/tools/check-warnings.py", line 311, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/runner/work/cpython/cpython/Doc/tools/check-warnings.py", line 279, in main
    with Path("Doc/sphinx-warnings.txt").open(encoding="UTF-8") as f:
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/pathlib.py", line 1013, in open
    return io.open(self, mode, buffering, encoding, errors, newline)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: 'Doc/sphinx-warnings.txt'

The 'Doc/sphinx-warnings.txt' file is a generated file so maybe we upgraded sphinx at some point and the new version does not generate the file if there's no warnings?

CPython versions tested on:

CPython main branch

Operating systems tested on:

No response

Linked PRs

• gh-118401: Docs: Use Sphinx short options #118403
• [3.12] gh-118401: Docs: Use Sphinx short options (GH-118403) #118407

[hugovk]

We upgraded Sphinx an hour ago: #118397

Thanks for the report, I'll check it.

[hugovk]

This is what's happening:

The PR branch still has the old Sphinx 7.2:

https://github.com/gaogaotiantian/cpython/blob/c9f96fd371487aff61bb588f0678139ccc914176/Doc/requirements.txt#L9

The error on the CI is actually in the previous step:

https://github.com/python/cpython/actions/runs/8883326110/job/24389960128?pr=118368#step:6:23

sphinx-build: error: unrecognized arguments: --quiet --nitpicky --fail-on-warning --warning-file

These long options were only added in Sphinx 7.3, and added to the workflow in #118397:

make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --nitpicky --fail-on-warning --keep-going --warning-file sphinx-warnings.txt" html

But your PR branch still has the short options:

make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going -w sphinx-warnings.txt" html

https://github.com/gaogaotiantian/cpython/blob/c9f96fd371487aff61bb588f0678139ccc914176/.github/workflows/reusable-docs.yml#L58

So it looks like, because the CI is started from a pull_request trigger (and not push), GitHub is installing Sphinx 7.2 as defined in your branch, but then running the Sphinx 7.3 command from main, and not the workflow from your branch?

The quick solution is to update your branch from main. But this will happen to other PRs too (I just saw another PR reference this issue as I was typing :), so instead I'll revert the changes to keep using the short options for longer.

[hugovk]

Please see PR #118403.

[hugovk]

Merged.

I restarted this docs build and it failed again:

https://github.com/python/cpython/actions/runs/8883326110/job/24395466270?pr=118368

It probably needs a new commit to re-sync or something? I updated the PR from main, and it now passed 👍

https://github.com/python/cpython/actions/runs/8885080408/job/24395617997?pr=118368

Hopefully it won't happen again for new PRs.

Thanks!