Skip to content

gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498

Open
sach98 wants to merge 1 commit into
python:mainfrom
sach98:docs-wsgiref-nitpick
Open

gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498
sach98 wants to merge 1 commit into
python:mainfrom
sach98:docs-wsgiref-nitpick

Conversation

@sach98

@sach98 sach98 commented Jul 22, 2026

Copy link
Copy Markdown

Fixes the 18 nit-picky Sphinx reference warnings in Doc/library/wsgiref.rst and removes the file from Doc/tools/.nitignore.

Where a correct target already exists, the reference is qualified so it resolves:

  • The filelike object's read and close become :meth:`~io.BufferedIOBase.read``` and :meth:~io.IOBase.close```. This matches the existing ``:meth:~io.BufferedIOBase.write``` reference further down the same file.
  • shift_path_info and guess_scheme are documented in wsgiref.util but were referenced from a different module context, so they are now qualified.
  • serve_forever and handle_request point at socketserver.BaseServer, which is where WSGIServer actually inherits them from.

The remaining names have no documented target anywhere: Headers.keys, Headers.values, Headers.items, WSGIServer.base_environ, BaseHandler.environ and SimpleHandler.stdin / stdout / stderr are described only in prose, and paste.lint is third party. Those use the ! prefix, which keeps the semantic markup and drops the link.

I kept this to reference fixes so the diff stays limited to removing the warnings. If you would prefer the undocumented Headers methods and handler attributes to become proper .. method:: and .. attribute:: entries instead (as was done for the lzma constants in gh-151949), I am happy to do that here or in a follow-up.

Verified with a fresh nit-picky build: warnings for this file go from 18 to 0, total build warnings go from 1352 to 1334, no new warnings elsewhere, and Doc/tools/check-warnings.py --fail-if-regression --fail-if-improved exits 0.

@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news labels Jul 22, 2026
@python-cla-bot

python-cla-bot Bot commented Jul 22, 2026

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.

CLA signed

@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #33712172 | 📁 Comparing 665de3a against main (3479e45)

  🔍 Preview build  

1 file changed
± library/wsgiref.html

@picnixz

picnixz commented Jul 24, 2026

Copy link
Copy Markdown
Member

The purpose was to document those attributes, not suppress them. Please do so.

@picnixz picnixz left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Please document the header objects properly.

@bedevere-app

bedevere-app Bot commented Jul 24, 2026

Copy link
Copy Markdown

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

And if you don't make the requested changes, you will be put in the comfy chair!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting changes docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

2 participants