GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-101100: Docs: Check Sphinx warnings and fail if improved by hugovk · Pull Request #106460 · python/cpython

Conversation

@hugovk

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

Uh oh!

There was an error while loading. Please reload this page.

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/

  • Issue: Fix all Sphinx reference warnings in the documentation #101100

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@hugovk
Check Sphinx warnings and fail if improved
a349080
@hugovk 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 bedevere-bot mentioned this pull request Jul 5, 2023
Fix all Sphinx reference warnings in the documentation #101100
Closed
@hugovk hugovk added the skip news label Jul 5, 2023
@hugovk
TEMP example warning
d9b230b
@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.
AlexWaygood reacted with hooray emoji
All reactions
  • 🎉 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@hugovk hugovk added the docs Documentation in the Doc dir label Jul 5, 2023
@hugovk

hugovk commented Jul 5, 2023 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

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)
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
hugovk added 2 commits July 5, 2023 22:48
@hugovk
Remove files from .nitignore that no longer have warnings
ddeea07
@hugovk
Revert "TEMP example warning"
2618b19 
This reverts commit d9b230b.
@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
@bedevere-bot bedevere-bot added the awaiting core review label Jul 5, 2023
hugovk added 2 commits July 6, 2023 18:04
@hugovk
Group warnings under filename
3522e2c
@hugovk
Merge branch 'main' into docs-check-sphinx-warnings
13522af
@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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@hugovk
Don't allow regressions in Doc/library/getopt.rst
7662a08
@hugovk hugovk added the needs backport to 3.12 only security fixes label Jul 21, 2023
@hugovk
Merge branch 'main' into docs-check-sphinx-warnings
d00f359
@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.
🐍🍒⛏🤖
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-bot bedevere-bot removed the awaiting core review label Jul 22, 2023
@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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington miss-islington assigned hugovk Jul 22, 2023
@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 👍
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@hugovk hugovk removed the needs backport to 3.12 only security fixes label Jul 22, 2023
@hugovk hugovk mentioned this pull request Jul 27, 2023
Infra: Check Sphinx warnings on CI python/peps#3213
Closed
@CAM-Gerlach CAM-Gerlach mentioned this pull request Aug 18, 2023
gh-101100: Only show GitHub check annotations on changed doc paragraphs #108065
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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@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.
🐍🍒⛏🤖
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
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 <[email protected]>
@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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@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.
hugovk reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
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 <[email protected]>
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 <[email protected]>

---------

Co-authored-by: Hugo van Kemenade <[email protected]>
@m-aciek m-aciek mentioned this pull request Jul 11, 2025
Docs: Sphinx warnings: fix passing command line arguments passed to the check script #136561
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 ezio-melotti is a code owner

Uh oh!

There was an error while loading. Please reload this page.

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.

Uh oh!

There was an error while loading. Please reload this page.

4 participants

@hugovk @miss-islington @CAM-Gerlach @bedevere-bot
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.