FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-101100: Docs: Check Sphinx warnings and fail if improved by hugovk · Pull Request #106460 · python/cpython · GitHub

/ cpython Public

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
ConversationCommits (8)ChecksFiles changed
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 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 changed the title Docs: Check Sphinx warnings and fail if improved gh-101100: Docs: Check Sphinx warnings and fail if improved Jul 5, 2023
bedevere-bot mentioned this pull request Jul 5, 2023
Closed

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 added the docs Documentation in the Doc dir label Jul 5, 2023

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 marked this pull request as ready for review July 5, 2023 20:19
hugovk requested a review from ezio-melotti as a code owner July 5, 2023 20:19

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

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 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 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 removed the needs backport to 3.12 only security fixes label Jul 22, 2023
hugovk mentioned this pull request Jul 27, 2023
Closed
CAM-Gerlach mentioned this pull request Aug 18, 2023
Merged

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 added the needs backport to 3.12 only security fixes label Aug 18, 2023

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 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
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
[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 commented Aug 18, 2023

Copy link
Copy Markdown

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

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

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
[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
[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 mentioned this pull request Jul 11, 2025
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

ezio-melotti Awaiting requested review from ezio-melotti ezio-melotti is a code owner

Assignees

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

Back | FazBrowse Home | New Git URL