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

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

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

1 participant