The better way to fix these two warnings would be to add documentation for these constants in thesocket module docs, if that documentation doesn't already exist. Then we'll also be able to reference these constants in the docs for other modules, as will users of intersphinx outside of CPython

Perhaps, but ISTR thesocket module doc explicitly mentions a whole raft of constants as coming from the underlying C socket(2) implementation. That is presumably to keep from duplicating underlying canonical documentation and to avoid introducing mistakes (think platform dependencies).

I understand it would be great to have the Python library docs completely self-contained, but I don't think that's the best way to go in some cases.

Fair point, there are probably too many in the socket module for us to list them all out explicitly!

In that case, we should explicitly list them inconf.py as silenced with a comment explaining why, to avoid introducing noise here, making it easy to change the decision in the future, and ensuring we have a consistent central record of it.

Given that many of the possible constants are only given in thesocket module doc as wildcards (e.g.,SO_*) I don't think that will work unless you only want to list a known (small) subset.

This stuff is really at the fringe between low-level Unix stuff and the relevant Python wrappers. According to Wikipedia, the first edition of Stevens'Unix Network Programming (the network programming bible when I was a wee lad) is 768 pages long. It's not at all clear to me that there's much to be gained by documenting a few socket options. It's not really going to flatten the socket programming learning curve much. Programmers will have to delve into the C socket documentation to do anything serious anyway.

Sorry about the soapbox.

What's the reason for disabling reference resolution here, sorry? Does it not work, for some reason? Ac:macro: is defined forPy_DEBUG, and the macro definition and surrounding text describes what it means for Python to be built in debug mode, so seems a useful reference here.

Also, this wording change seems a bit incongruous to my eye and the breaks don't either minimize diffs or follow the semantic structure. Therefore, I'd suggest either simplifying the structure and wording with more logical breaks:

or minimizing diffs to just the essential fixes

Probably just confusion on my part, though I think in discussing changes totest.rst we might have gone back and forth a bit. Note that the meaning and effects of debug builds are scattered in multiple locations. In my mind defining thePy_DEBUG macro is just the marker for C programmers for what you really care about, creating a debug build. That's discussed in to sections inusing/configure.rst andc-api/intro.rst.

In that case, we should explicitly list them inconf.py as silenced with a comment explaining why, to avoid introducing noise here, making it easy to change the decision in the future, and ensuring we have a consistent central record of it.

This is a constant in an underscored name, test module, so it's not required to document it, but given the entire description of this function is "return ", which doesn't seem terribly useful if said constant is entirely undocumented, it seems worth at least briefly touching on what that actually means here (which the warning is a canary for).

I'm guessing the reference must be suppressed in some other way, because no hyperlink shows up in the generated HTML (and no warning is emitted by Sphinx). You'll have to take this up with someone above my pay grade.

This is an purposefully undocumented module, I'm guessing?

I couldn't begin to guess why it's undocumented. Maybe it's meant to be semantically identical to the relevantthreading module synchronization primitives?

__all__ = [    'Lock', 'RLock', 'Semaphore', 'BoundedSemaphore', 'Condition', 'Event'    ]

I see this comment preceding an import which it suggests might fail:

# Try to import the mp.synchronize module cleanly, if it fails# raise ImportError for platforms lacking a working sem_open implementation.# See issue 3770

There is also a note about this possibility in themultiprocessing module documentation.

This is a valid, public method ofWarningsRecorder, a class publicly documented just below, that is missing its documentation. Therefore, this warning shouldn't be silenced, as again it indicates a legitimite gap in the docs. The simplest solution seems to move this line to a.. method under theWarningsRecorder class to properly document the method there, instead of overloading the already long and complexcheck_warnings context description with details of the object it returns.

I changed the text to:meth:``~WarningsRecorder.reset`` (how in the heck do I make the raw ReST display correctly in Markdown???) which is fine as far as that goes, but there is no documentation of either the class or the reset method. I'll leave it as-is. There will be a nitpick warning:

.../Doc/library/test.rst:1728: WARNING: py:meth reference target not found: WarningsRecorder.reset

(how in the heck do I make the raw ReST display correctly in Markdown???)

Use the fact that GitHub supports HTML tags and escape backquotes:

<code>:meth:\`~WarningsRecorder.reset\`</code>

produces:meth:`~WarningsRecorder.reset`.

This existing reference resolves but entirely incorrectly; it implieswarnings is an "attribute" of thetest.support.warnings_helper module, and furthermore actually falls back to link to thewarnings stdlib module instead, which is entirely not what is intended. It should presumably be moved to where it belongs, under the class below, instead, to both avoid the misleading reference and properly document it.

This is one place where it would be real nice if Sphinx applied some simple semantics to the refs. Something which is an attribute clearly can't be a module. I've qualified the reference. As with thereset reference, it is now broken.

.../Doc/library/test.rst:1719: WARNING: py:attr reference target not found: WarningsRecorder.warnings

Both thereset andwarnings items are fully qualified, so even though the links don't work, the full names are displayed.