Skip to content

gh-101100: Fix sphinx warnings in library/socketserver.rst #110207

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 2 commits into from
Oct 10, 2023
Merged

gh-101100: Fix sphinx warnings in library/socketserver.rst #110207

merged 2 commits into from
Oct 10, 2023

Conversation

sobolevn
Copy link
Member

@sobolevn sobolevn commented Oct 2, 2023 •
edited by github-actions bot
Loading

Before:

/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:119: WARNING: py:meth reference target not found: socketserver.ForkingMixIn.server_close
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:119: WARNING: py:attr reference target not found: socketserver.ForkingMixIn.block_on_close
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:123: WARNING: py:meth reference target not found: socketserver.ThreadingMixIn.server_close
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:123: WARNING: py:attr reference target not found: socketserver.ThreadingMixIn.block_on_close
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:123: WARNING: py:data reference target not found: ThreadingMixIn.daemon_threads
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:132: WARNING: py:meth reference target not found: socketserver.ForkingMixIn.server_close
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:132: WARNING: py:meth reference target not found: socketserver.ThreadingMixIn.server_close
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:132: WARNING: py:attr reference target not found: socketserver.ForkingMixIn.block_on_close
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:413: WARNING: py:attr reference target not found: self.request
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:413: WARNING: py:attr reference target not found: self.client_address
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:413: WARNING: py:attr reference target not found: self.server
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:419: WARNING: py:attr reference target not found: self.request
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:419: WARNING: py:attr reference target not found: self.request
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:419: WARNING: py:attr reference target not found: self.request
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:434: WARNING: py:attr reference target not found: self.rfile
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:434: WARNING: py:attr reference target not found: self.wfile
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:434: WARNING: py:attr reference target not found: self.rfile
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:434: WARNING: py:attr reference target not found: self.wfile
/Users/sobolev/Desktop/cpython/Doc/library/socketserver.rst:444: WARNING: py:attr reference target not found: StreamRequestHandler.wfile

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

@sobolevn sobolevn requested review from hugovk and AA-Turner October 2, 2023 09:50
@bedevere-app bedevere-app bot mentioned this pull request Oct 2, 2023
Open
@hugovk hugovk added skip news needs backport to 3.11 only security fixes needs backport to 3.12 only security fixes labels Oct 2, 2023
hugovk
hugovk reviewed Oct 2, 2023
View reviewed changes
Doc/library/socketserver.rst Outdated
@@ -116,23 +116,23 @@ server is the address family.
:class:`ForkingMixIn` and the Forking classes mentioned below are
only available on POSIX platforms that support :func:`~os.fork`.

:meth:`socketserver.ForkingMixIn.server_close` waits until all child
:meth:`!ForkingMixIn.server_close` waits until all child
Copy link
Member

Choose a reason for hiding this comment

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

Should all these be documented rather than excluding via !?

Copy link
Member Author

Choose a reason for hiding this comment

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

They are documented, but in a base class. I don't think that we should document implementation methods, they are just, well, implementations :)

Copy link
Member Author

Choose a reason for hiding this comment

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

cpython/Doc/library/socketserver.rst

Line 251 in 777f882

.. method:: server_close()

Copy link
Member

Choose a reason for hiding this comment

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

Verbose, but a potential option?

Suggested change
:meth:`!ForkingMixIn.server_close` waits until all child
:meth:`ForkingMixIn.server_close <BaseServer.server_close>` waits until all child

I think it might be worth documenting these methods, though, as their behaviour does differ significantly.

A

Copy link
Member Author

Choose a reason for hiding this comment

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

I like the verbose option :)

I don't agree that their behavior is different: they all just clean things up afterwards. But in a different way (which is an implementation detail that should not be a part of the docs).

@ambv ambv merged commit 756062b into python:main Oct 10, 2023
@miss-islington
Copy link
Contributor

Thanks @sobolevn for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Oct 10, 2023
@sobolevn @miss-islington
pythongh-101100: Fix sphinx warnings in library/socketserver.rst (p…
4f98353 
…ythonGH-110207)

(cherry picked from commit 756062b)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
@bedevere-app
Copy link

bedevere-app bot commented Oct 10, 2023

GH-110623 is a backport of this pull request to the 3.12 branch.

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Oct 10, 2023
@sobolevn @miss-islington
pythongh-101100: Fix sphinx warnings in library/socketserver.rst (p…
0a3d2a8 
…ythonGH-110207)

(cherry picked from commit 756062b)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
@bedevere-app bedevere-app bot removed the needs backport to 3.12 only security fixes label Oct 10, 2023
@bedevere-app
Copy link

bedevere-app bot commented Oct 10, 2023

GH-110624 is a backport of this pull request to the 3.11 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.11 only security fixes label Oct 10, 2023
ambv pushed a commit that referenced this pull request Oct 10, 2023
@miss-islington @sobolevn
[3.12] gh-101100: Fix sphinx warnings in library/socketserver.rst (G…
80e4abe 
…H-110207) (GH-110623)

(cherry picked from commit 756062b)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
ambv pushed a commit that referenced this pull request Oct 10, 2023
@miss-islington @sobolevn
[3.11] gh-101100: Fix sphinx warnings in library/socketserver.rst (G…
de62c2c 
…H-110207) (GH-110624)

(cherry picked from commit 756062b)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
Glyphack pushed a commit to Glyphack/cpython that referenced this pull request Sep 2, 2024
@sobolevn @Glyphack
pythongh-101100: Fix sphinx warnings in library/socketserver.rst (p…
ffaf476 
…ythonGH-110207)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@hugovk hugovk hugovk left review comments

@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner

Assignees
No one assigned
Labels
skip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@sobolevn @miss-islington @hugovk @AA-Turner @ambv