GH-101100: Fix reference warnings for socket methods

[AA-Turner]

This doesn't tackle the constants.

• Issue: Fix all Sphinx reference warnings in the documentation #101100

---

📚 Documentation preview 📚: https://cpython-previews--110114.org.readthedocs.build/en/110114/library/socket.html

[serhiy-storchaka]

I think that in all cases where it refers to socket() as a function, it should keep :func: role.

[serhiy-storchaka]

It says "the socket() function". I think that it is better to leave references to class as a function in the context where the fact that it is a callable is more important than the fact that it is also a type. There are a lot of precedences with int(), str(), range(), map(), etc.

[AA-Turner]

Would you suggest adding a .. function:: socket directive (potentially just above .. class:: socket)?

[serhiy-storchaka]

It is not needed, the role type should not affect links. For example :func:`int` and :class:`int` refer to the same .. class:: declaration. The difference is that :func: adds ().

[AA-Turner]

I tried this locally (replacing all :class:`.socket` with :func:`socket` ) -- the problem is that the cross-reference goes to the module object definition (library/socket.html#module-socket) rather than the socket callable.

So I think our best option is to add a .. function:: socket directive.

A

[AA-Turner]

Looking further, socket() was previously documented as a function, but #23960 changed it to be documented as a class. Perhaps we could change it back? map is documented as a function, for example.

[serhiy-storchaka]

I think that the problem is that if you use a reference starting with ., Sphinx switches in more strict mode that checks the role type, so :func:`.socket` does not find the class declaration. But :func:`socket.socket` may work.

[hugovk]

@AA-Turner Please could you resolve the conflicts? Then I think we're ready to merge.

[serhiy-storchaka]

I restored the use of the .. class:: directive for socket. It fixes rendering for "the socket constructor". The :func: references work when specify the full qualified name.

Also fixed references for few more methods.

[miss-islington-app]

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

[bedevere-app]

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

[bedevere-app]

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