Convert unsemantic monospaced directives to :ref:

[InSyncWithFoo]

Directives like :class:, :func:, etc. auto-apply a monospaced font to the displayed text, which doesn't look very nice if used unsemantically. :ref: directives are the way to go when it comes to internal links with non-code text, and most of other internal links already follow this.

For example, this line in Doc/library/typing.rst:

cpython/Doc/library/typing.rst

Line 307 in b07f232

variadic number of arguments, :func:`overloaded functions <overload>`, or

...should be changed to:

variadic number of arguments, :ref:`overloaded functions <overload>`

And this line:

cpython/Doc/library/typing.rst

Line 2775 in b07f232

.. decorator:: overload

...needs an explicit target:

.. _overload:

.. decorator:: overload

Linked PRs

• gh-111151: Convert monospaced directives to :ref: #111152
• [3.12] gh-111151: Convert monospaced directives to :ref: (GH-111152) #111269
• [3.11] gh-111151: Convert monospaced directives to :ref: (GH-111152) #111270

[hugovk]

If we were talking about overload directly, monospace is good there.

But if we're essentially overriding it with other text, normal font seems more sensible.

• :func:`overload` in monospace -> "overload"
• :func:`overloaded functions <overload>` in normal font -> "overloaded functions"

I wonder if this is something Sphinx should be doing? But maybe the override text is actually another function name in some cases, and it's not safe for a blanket assumption.

cc @AA-Turner

[InSyncWithFoo]

@hugovk Sorry for the generic title and description. I'm talking about unsemantical monospaced directives. The line I cited currently displays as:

variadic number of arguments, overloaded functions, or

...which reads unnatural since "overloaded functions" is not a piece of code, nor is it a function, class or method.

A valid example for comparison:

To frobnicate, the :class:`foo.Bar` class may be used.
Its :meth:`baz_qux <foo.Bar.baz_qux>` method provides a nice way to do so.

...which renders as:

To frobnicate, the foo.Bar class may be used. Its baz_qux method provides a nice way to do so.

The alternate display text is used semantically here since baz_qux is the name of a method of class foo.Bar (and hence a piece of code), and repeating the class name twice may look not as nice because that piece of information is already clear from the content of the text itself.

[hugovk]

No need to apologise, I got the idea and your PR looks good from a quick check.

To nitpick, an alternative to:

:meth:`baz_qux <foo.Bar.baz_qux>` 

Is something like:

:meth:`~foo.Bar.baz_qux`

But for another example, maybe we want to display only Bar.baz_qux so would use something like:

:meth:`Bar.baz_qux <foo.Bar.baz_qux>`

Which answers my question that we can't have a generic Sphinx solution for this, and specific fix like your PR is what we need. Thanks, I'll review the PR later.