gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498
Conversation
Documentation build overview
|
|
The purpose was to document those attributes, not suppress them. Please do so. |
picnixz
left a comment
There was a problem hiding this comment.
Please document the header objects properly.
|
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 And if you don't make the requested changes, you will be put in the comfy chair! |
Fixes the 18 nit-picky Sphinx reference warnings in
Doc/library/wsgiref.rstand removes the file fromDoc/tools/.nitignore.Where a correct target already exists, the reference is qualified so it resolves:
readandclosebecome: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_infoandguess_schemeare documented inwsgiref.utilbut were referenced from a different module context, so they are now qualified.serve_foreverandhandle_requestpoint atsocketserver.BaseServer, which is whereWSGIServeractually inherits them from.The remaining names have no documented target anywhere:
Headers.keys,Headers.values,Headers.items,WSGIServer.base_environ,BaseHandler.environandSimpleHandler.stdin/stdout/stderrare described only in prose, andpaste.lintis 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
Headersmethods 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-improvedexits 0.Doc/library/files #151950