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: Only show GitHub check annotations on changed doc paragraphs by CAM-Gerlach · Pull Request #108065 · python/cpython

Conversation

@CAM-Gerlach

@CAM-Gerlach CAM-Gerlach commented Aug 16, 2023 •
edited
Loading

Uh oh!

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

Copy link
Copy Markdown
Member

PR #102513 implemented support for displaying Sphinx warnings on changed files inline in the GitHub UI, which can be a useful aid to authors that they've fixed any defects on the lines they've touched and not introduced new ones.

However, annotations are shown on an entire file, regardless of whether the line the warning was issued on was within or even near those actually modified by the PR. While this has helped motivate large-scale cleanup of many of these warnings, as I commented when this was first deployed it has naturally led to a serious amount of noise, annoyance and confusion for PR authors seeing warnings on lines they had nothing to do with, which in turn leads to the understandable temptation for authors to ignore valid warnings or just silencing them, hiding rather than fixing the underlying defect.

The solution is, naturally, to only show warnings on modified lines, which is somewhat complicated by the fact that warning lines are only necessarily accurate at the paragraph level, requiring some additional processing. After much delay and burnout, I've finally gotten around to implementing it myself with this PR.

As a bonus, the script now works equally as well locally as remotely; just pass the commits/branches/tags to compare with --check-and-annotate-changes <base> <branch>, or use the default (comparing the changes on the current HEAD with the merge base in the local main). Handy!

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

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

Sorry, something went wrong.

Uh oh!

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

hugovk reacted with rocket emoji
All reactions
  • 🚀 1 reaction
@CAM-Gerlach CAM-Gerlach added docs Documentation in the Doc dir skip news labels Aug 16, 2023
@CAM-Gerlach CAM-Gerlach self-assigned this Aug 16, 2023
@bedevere-bot bedevere-bot mentioned this pull request Aug 15, 2023
Fix all Sphinx reference warnings in the documentation #101100
Closed
@CAM-Gerlach
CAM-Gerlach force-pushed the only-nitpicky-warn-on-changed-paras branch 4 times, most recently from 7bf133e to d4f66b9 Compare August 16, 2023 23:39
AA-Turner
AA-Turner reviewed Aug 17, 2023
View reviewed changes

@AA-Turner AA-Turner left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for this work! Some initial comments:

Sorry, something went wrong.

Uh oh!

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

CAM-Gerlach and hugovk reacted with thumbs up emoji
All reactions
  • 👍 2 reactions
Comment thread .github/workflows/reusable-docs.yml Resolved

Uh oh!

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

Comment thread Doc/library/datetime.rst Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

@CAM-Gerlach
CAM-Gerlach force-pushed the only-nitpicky-warn-on-changed-paras branch from 37f8a2e to b6c794f Compare August 17, 2023 01:32
@CAM-Gerlach
Only show GitHub check annotations on changed doc paragraphs
67a6dce
@CAM-Gerlach
CAM-Gerlach force-pushed the only-nitpicky-warn-on-changed-paras branch from b6c794f to 67a6dce Compare August 17, 2023 02:37
@CAM-Gerlach
CAM-Gerlach marked this pull request as ready for review August 17, 2023 03:20
@CAM-Gerlach
CAM-Gerlach requested review from ezio-melotti and hugovk as code owners August 17, 2023 03:20
@bedevere-bot bedevere-bot added the awaiting core review label Aug 17, 2023
@CAM-Gerlach
CAM-Gerlach requested a review from AA-Turner August 17, 2023 03:20
hugovk
hugovk reviewed Aug 17, 2023
View reviewed changes

@hugovk hugovk left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you very much for this!

A few initial comments.

Sorry, something went wrong.

Uh oh!

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

All reactions
Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

hugovk
hugovk reviewed Aug 17, 2023
View reviewed changes
Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

@CAM-Gerlach
CAM-Gerlach requested review from abalkin and pganssle as code owners August 17, 2023 17:36
@CAM-Gerlach
CAM-Gerlach force-pushed the only-nitpicky-warn-on-changed-paras branch from 75a2023 to 263c3c6 Compare August 17, 2023 17:47
@CAM-Gerlach
CAM-Gerlach removed request for abalkin and pganssle August 17, 2023 18:34
@CAM-Gerlach CAM-Gerlach added the DO-NOT-MERGE label Aug 17, 2023
@CAM-Gerlach

CAM-Gerlach commented Aug 17, 2023

Copy link
Copy Markdown
Member Author

(Just to note, I made another commit to continue to test that the annotations appear (and don't appear) as expected on added files, and on added, fixed and modified warnings in modified files. It deliberately fails the new-warnings check, and I also marked it DO-NOT-MERGE just to be safe; once this is approved and otherwise ready to merge, I'll drop that commit and then queue it for automerge.)

hugovk and AA-Turner reacted with thumbs up emoji
All reactions
  • 👍 2 reactions

Sorry, something went wrong.

Uh oh!

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

AA-Turner
AA-Turner reviewed Aug 17, 2023
View reviewed changes

@AA-Turner AA-Turner left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some further comments:

Sorry, something went wrong.

Uh oh!

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

All reactions
Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

Comment thread Doc/tools/check-warnings.py Resolved

Uh oh!

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

@CAM-Gerlach
CAM-Gerlach force-pushed the only-nitpicky-warn-on-changed-paras branch 2 times, most recently from cae535a to 7a6eef9 Compare August 18, 2023 03:52
@CAM-Gerlach @hugovk
Improve check-warnings script arg parsing following Hugo's suggestions
887ca3f
Co-authored-by: Hugo van Kemenade <[email protected]>
CAM-Gerlach and others added 3 commits August 18, 2023 00:04
@CAM-Gerlach
Factor filtering warnings by modified diffs into helper function
70459ca
@CAM-Gerlach
Build docs on unmerged branch so warning lines match & avoid deep clone
d8344a9
@CAM-Gerlach @AA-Turner
Apply a few final review suggestions from Adam
b006d01
Co-authored-by: Adam Turner <[email protected]>
@CAM-Gerlach
CAM-Gerlach force-pushed the only-nitpicky-warn-on-changed-paras branch from 6c98380 to b006d01 Compare August 18, 2023 05:12
@CAM-Gerlach CAM-Gerlach removed the DO-NOT-MERGE label Aug 18, 2023
@CAM-Gerlach
CAM-Gerlach requested review from AA-Turner and hugovk August 18, 2023 05:17
@CAM-Gerlach

CAM-Gerlach commented Aug 18, 2023

Copy link
Copy Markdown
Member Author

Since the final changes were just to a comment and a __future__ import, I've dropped the various test commits to confirm various common and edge cases, so this should be ready to merge pending any final comments/suggestions (which hopefully aren't substantial or I'll have to temporarily add them back, heh).

All reactions

Sorry, something went wrong.

Uh oh!

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

AA-Turner
AA-Turner approved these changes Aug 18, 2023
View reviewed changes

@AA-Turner AA-Turner left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks again for all the work on this!

A

Sorry, something went wrong.

Uh oh!

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

CAM-Gerlach reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
hugovk
hugovk approved these changes Aug 18, 2023
View reviewed changes

@hugovk hugovk left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Do we need to backport this?

Sorry, something went wrong.

Uh oh!

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

CAM-Gerlach reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
@bedevere-bot bedevere-bot added awaiting merge and removed awaiting core review labels Aug 18, 2023
@CAM-Gerlach

CAM-Gerlach commented Aug 18, 2023

Copy link
Copy Markdown
Member Author

Do we need to backport this?

I was actually just about to comment on this now as I remembered that I'd forgotten to do so yesterday. The same problems this fixes (warning spam, as well as line numbers being off, etc) will be present in the Files Changed views on the 3.12 branch, where the script is present (its not on 3.11).

We will need to backport PR #106460 first though as it makes comprehensive changes to these same files; its backport was deferred to after the reusable docs changes were merged, which they now are, so it seems we should be able to just go ahead with that backport first, and then this should backport cleanly.

(In case you didn't see it, I posted this reply after the relevant comment chain had already been resolved, which you might find interesting)

All reactions

Sorry, something went wrong.

Uh oh!

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

This was referenced Aug 18, 2023
gh-101100: Docs: Check Sphinx warnings and fail if improved #106460
Merged
[3.12] gh-101100: Docs: Check Sphinx warnings and fail if improved (GH-106460) #108116
Merged
@CAM-Gerlach CAM-Gerlach added 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 Author

I had to manually backport #106460 due to some merge conflicts in the .nitignore, but it should be good to merge as soon as Thomas gets the chance to review it, and then we can merge and backport this (hopefully cleanly).

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

CAM-Gerlach commented Aug 19, 2023

Copy link
Copy Markdown
Member Author

Alrighty, looks like that backport got in, so I guess we're gogo on this one at last!

hugovk reacted with rocket emoji
All reactions
  • 🚀 1 reaction

Sorry, something went wrong.

Uh oh!

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

@CAM-Gerlach
CAM-Gerlach merged commit eb953d6 into python:main Aug 19, 2023
@miss-islington

miss-islington commented Aug 19, 2023

Copy link
Copy Markdown
Contributor

Thanks @CAM-Gerlach 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 merge label Aug 19, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 19, 2023
@CAM-Gerlach @hugovk
@AA-Turner @miss-islington
pythongh-101100: Only show GitHub check annotations on changed doc pa…
4203374
…ragraphs (pythonGH-108065)

* Only show GitHub check annotations on changed doc paragraphs
* Improve check-warnings script arg parsing following Hugo's suggestions
* Factor filtering warnings by modified diffs into helper function
* Build docs on unmerged branch so warning lines match & avoid deep clone

---------

(cherry picked from commit eb953d6)

Co-authored-by: C.A.M. Gerlach <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
@bedevere-bot

bedevere-bot commented Aug 19, 2023

Copy link
Copy Markdown

GH-108127 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 19, 2023
Yhg1s pushed a commit that referenced this pull request Aug 19, 2023
@miss-islington @CAM-Gerlach
@hugovk @AA-Turner
[3.12] gh-101100: Only show GitHub check annotations on changed doc p…
71e3581
…aragraphs (GH-108065) (#108127)

gh-101100: Only show GitHub check annotations on changed doc paragraphs (GH-108065)

* Only show GitHub check annotations on changed doc paragraphs
* Improve check-warnings script arg parsing following Hugo's suggestions
* Factor filtering warnings by modified diffs into helper function
* Build docs on unmerged branch so warning lines match & avoid deep clone

---------

(cherry picked from commit eb953d6)

Co-authored-by: C.A.M. Gerlach <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
@hugovk hugovk mentioned this pull request Sep 15, 2023
gh-109408: Run patchcheck in GitHub Actions #109459
Closed
@AA-Turner AA-Turner mentioned this pull request Feb 3, 2025
Convert change detection to a Python script #129627
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hugovk hugovk hugovk approved these changes
@AA-Turner AA-Turner AA-Turner approved these changes
@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

@CAM-Gerlach CAM-Gerlach

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.

5 participants

@CAM-Gerlach @miss-islington @bedevere-bot @hugovk @AA-Turner
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.