◐ Shell
reader mode source ↗
Skip to content

gh-101100: Docs: Check Sphinx warnings and fail if improved#106460

Merged
hugovk merged 8 commits into
python:mainfrom
hugovk:docs-check-sphinx-warnings
Jul 22, 2023
Merged

gh-101100: Docs: Check Sphinx warnings and fail if improved#106460
hugovk merged 8 commits into
python:mainfrom
hugovk:docs-check-sphinx-warnings

Conversation

@hugovk

@hugovk hugovk commented Jul 5, 2023 •
edited by bedevere-bot
Loading

Copy link
Copy Markdown
Member

Recently I improved some colour contrast for Pygments, and they have a file of current contrast ratios. If they're improved by a PR, the CI will fail to make sure the ratio constants are updated, to ensure continual improvement with no regressions.

This is a good idea!

Let's add it here, to check if any files in .nitignore (which may have Sphinx warnings) switch to having no warnings. Then we can remove them from .nitignore to make sure they remain free of warnings.

I was going to add another Sphinx build, a fourth, to touch the relevant files, so only those would be rebuilt. But four builds is far too many!

Instead, let's build only once and save the warnings to a file. Then we can process the file and do the three phases:

  • Annotate PRs with Sphinx nitpicks (as before)
  • Ensure some files always pass Sphinx nit-picky mode (as before)
  • Check for improved files that can be removed from .nitignore (new!)

📚 Documentation preview 📚: https://cpython-previews--106460.org.readthedocs.build/

@hugovk hugovk changed the title Docs: Check Sphinx warnings and fail if improved Jul 5, 2023
@bedevere-bot bedevere-bot mentioned this pull request Jul 5, 2023
Open
@hugovk

hugovk commented Jul 5, 2023

Copy link
Copy Markdown
Member Author

Marked as draft to make some temporary commits to demonstrate errors.

First, the new check finds five files that no longer contain warnings!

Congratulations! You improved:

Doc/c-api/dict.rst
Doc/c-api/weakref.rst
Doc/library/cgi.rst
Doc/library/cmath.rst
Doc/library/curses.ascii.rst

Please remove from Doc/tools/.nitignore

https://github.com/python/cpython/actions/runs/5468129112/jobs/9955353278?pr=106460

Some of these files were deleted along with PEP 594's dead batteries. Others have been "accidentally" fixed since .nitignore was first compiled.

@hugovk hugovk added the docs Documentation in the Doc dir label Jul 5, 2023
@hugovk

hugovk commented Jul 5, 2023 •
edited
Loading

Copy link
Copy Markdown
Member Author

Adding a (temporary) warning to 3.12.rst, which is not allowed warning, gives:

Error: must not contain warnings:

Doc/whatsnew/3.12.rst
  9: WARNING: c:func reference target not found: PyFrame_BlockSetup

Plus the file is annotated.

https://github.com/python/cpython/actions/runs/5468217855/jobs/9955568557?pr=106460

(Edit: output updated per 3522e2c)

@hugovk hugovk marked this pull request as ready for review July 5, 2023 20:19
@hugovk hugovk requested a review from ezio-melotti as a code owner July 5, 2023 20:19
@hugovk

hugovk commented Jul 19, 2023

Copy link
Copy Markdown
Member Author

Updating from main finds a new file that's been fixed! 🎉

Congratulations! You improved:

Doc/library/getopt.rst

Please remove from Doc/tools/.nitignore

@hugovk hugovk added the needs backport to 3.12 only security fixes label Jul 21, 2023
@hugovk hugovk enabled auto-merge (squash) July 22, 2023 08:00
@hugovk hugovk merged commit 806d7c9 into python:main Jul 22, 2023
@hugovk hugovk deleted the docs-check-sphinx-warnings branch July 22, 2023 08:12
@miss-islington

miss-islington commented Jul 22, 2023

Copy link
Copy Markdown
Contributor

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

@miss-islington

miss-islington commented Jul 22, 2023

Copy link
Copy Markdown
Contributor

Sorry @hugovk, I had trouble checking out the 3.12 backport branch.
Please retry by removing and re-adding the "needs backport to 3.12" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker 806d7c98a5da5c1fd2e52a5b666f36ca4f545092 3.12

@hugovk

hugovk commented Jul 22, 2023

Copy link
Copy Markdown
Member Author

3.12 doesn't yet have the refactored .github/workflows/reusable-docs.yml workflow, so let's leave this backport for that 👍

@hugovk hugovk removed the only security fixes label Jul 22, 2023
@hugovk hugovk mentioned this pull request Jul 27, 2023
Closed
@CAM-Gerlach CAM-Gerlach mentioned this pull request Aug 18, 2023
Merged
@CAM-Gerlach

CAM-Gerlach commented Aug 18, 2023

Copy link
Copy Markdown
Member

Looks like that was landed and this is required to backport #108065 , so retrying the backport.

@CAM-Gerlach CAM-Gerlach added the needs backport to 3.12 only security fixes label Aug 18, 2023
@miss-islington

miss-islington commented Aug 18, 2023

Copy link
Copy Markdown
Contributor

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

@miss-islington

miss-islington commented Aug 18, 2023

Copy link
Copy Markdown
Contributor

Sorry, @hugovk, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 806d7c98a5da5c1fd2e52a5b666f36ca4f545092 3.12

CAM-Gerlach pushed a commit to CAM-Gerlach/cpython that referenced this pull request Aug 18, 2023
@hugovk @CAM-Gerlach
pythongh-101100: Docs: Check Sphinx warnings and fail if improved (py… …
3bd0fbe 
…thon#106460)

(cherry picked from commit 806d7c9)
CAM-Gerlach added a commit to CAM-Gerlach/cpython that referenced this pull request Aug 18, 2023
@CAM-Gerlach @hugovk
[3.12] pythongh-101100: Docs: Check Sphinx warnings and fail if impro… …
6a4df40 
…ved (pythonGH-106460).

(cherry picked from commit 806d7c9)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
@bedevere-bot

bedevere-bot commented Aug 18, 2023

Copy link
Copy Markdown

GH-108116 is a backport of this pull request to the 3.12 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.12 only security fixes label Aug 18, 2023
@CAM-Gerlach

CAM-Gerlach commented Aug 18, 2023

Copy link
Copy Markdown
Member

Had to manually backport it due to conflicts in .nitignore, and might need to resolve a few additional discrepancies there once it builds.

CAM-Gerlach added a commit to CAM-Gerlach/cpython that referenced this pull request Aug 18, 2023
@CAM-Gerlach @hugovk
[3.12] pythongh-101100: Docs: Check Sphinx warnings and fail if impro… …
78dfd24 
…ved (pythonGH-106460).

(cherry picked from commit 806d7c9)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Yhg1s pushed a commit that referenced this pull request Aug 18, 2023
@CAM-Gerlach @hugovk
[3.12] gh-101100: Docs: Check Sphinx warnings and fail if improved (G… …
daed54d 
…H-106460) (#108116)

* gh-101100: Docs: Check Sphinx warnings and fail if improved (#106460)

(cherry picked from commit 806d7c9)

* [3.12] gh-101100: Docs: Check Sphinx warnings and fail if improved (GH-106460).
(cherry picked from commit 806d7c9)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

---------

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
@m-aciek m-aciek mentioned this pull request Jul 11, 2025
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ezio-melotti ezio-melotti Awaiting requested review from ezio-melotti

Assignees

@hugovk hugovk

Labels

docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@hugovk @miss-islington @CAM-Gerlach @bedevere-bot