gh-101100: Fix Sphinx warnings in library/random.rst

[hugovk]

Fix 7 Sphinx warnings:

❯ SPHINXERRORHANDLING=-n PATH=./venv/bin:$PATH sphinx-build -b html -d build/doctrees -j auto -n . build/html ./library/random.rst 2>&1 | grep WARNING | tee >(wc -l)
Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.random
Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.seed
Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.getstate
Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.setstate
Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.getrandbits
Doc/library/random.rst:416: WARNING: py:class reference target not found: NoneType
Doc/library/random.rst:443: WARNING: py:meth reference target not found: Random.random
       7

And update a couple of URL redirects.

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

---

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

[serhiy-storchaka]

I am not sure that it is right to replace references to Random methods by references to global functions.

@rhettinger, what do you think?

[rhettinger]

@serhiy-storchaka I also think the proposed edit is incorrect.

[hugovk]

Okay, how's this? 4bbac89

Or should they be separately documented?

[rhettinger]

@AlexWaygood can you take a look at this and make a suggestion. Is there a way to address the Sphinx warnings without damaging the existing correct useful links that are currently being rendered?

[hugovk]

@AlexWaygood can you take a look at this and make a suggestion. Is there a way to address the Sphinx warnings without damaging the existing correct useful links that are currently being rendered?

This PR doesn't break any existing links.

The existing links are not actually links: the warnings indicate that they fail to render, because there are no docs at the target location.

The PR changes links these broken links to unlinked method names, which render the same, and do not issue any reference warnings.

Before:

After:

And the HTML markup is identical:

Before	After

Edit: An alternative is to add documentation for these class methods, so the links render correctly. Is this preferable?

[serhiy-storchaka]

Is there a way to address the Sphinx warnings without damaging the existing correct useful links that are currently being rendered?

Currently these references do not render as links, because targets are not defined. This PR replaces the method references with the global function references, which will be rendered as links. I.e. instead of seed() there will be seed(). On one hand, working links are good, on other hand, they refer to global functions rather than Random methods. Methods of Random subclass are purposed to be overridden, but "overriding" global functions is something different. This can cause confusion. But it is the only place where seed() is described, there is no separate documentation for methods. Links allow you to see signature and semantic of the methods. So there are pluses and minuses in these changes. I'm not going to decide which prevails and leave it up to you, @rhettinger.

[AlexWaygood]

I think Hugo is correct here. When it comes to methods such as random.Random.seed, which currently do not have a canonical anchor for us to link to, we have three options, as far as I can see:

1. Instead of telling Sphinx to add a link to random.Random.seed (which it can't do at the moment), tell Sphinx to add a link to random.seed(). This is what Hugo did in his first commit.
2. Tell Sphinx not to bother trying to add a link to random.Random.seed. This is what the PR currently proposes.
3. Add a canonical anchor for us to link to when random.Random.seed is referenced, that is separate to random.seed. This is possibly the most principled course of action, but will involve some degree of duplication, since random.Random.seed() and random.seed() do basically the same thing. (But not necessarily too much duplication -- we could simply document the method with a one-line entry: "See random.seed".)

[serhiy-storchaka]

0. (the current status) Keep it as silenced Sphinx warnings, as a reminder to solve it later, when we will have opportunity.

Remember, that there is always the 0th variant.

[hugovk]

0. (the current status) Keep it as silenced Sphinx warnings, as a reminder to solve it later, when we will have opportunity.

I'm willing to solve it now, if only we can decide how to solve it :)

The first thing I tried was like this:

-:meth:`~Random.random`
+:meth:`~!Random.random`

They render the same as the original, but we still get warnings:

Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.random
Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.seed
Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.getstate
Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.setstate
Doc/library/random.rst:36: WARNING: py:meth reference target not found: Random.getrandbits
Doc/library/random.rst:443: WARNING: py:meth reference target not found: Random.random

Is there another way to silence the warnings?

(Other than !Random.random, which renders as Random.random() instead of random().

[hugovk]

@rhettinger Which of Alex's suggestions do you prefer?

[hugovk]

Ah sorry, I just noticed you had assigned this to @AlexWaygood.

@AlexWaygood, which do you prefer?

[AlexWaygood]

Ah sorry, I just noticed you had assigned this to @AlexWaygood.

@AlexWaygood, which do you prefer?

I quite like the idea of option (3). I think adding a short stub entry for each of these methods might be useful, -- maybe just 1-2 sentences for each. Something like "Override this method in subclasses to customise blah behaviour of Random instances".

[hugovk]

Thanks, updated to add stub entries:

https://cpython-previews--112981.org.readthedocs.build/en/112981/library/random.html#random.Random

Also, in some examples, move the comments in so they fit without needing to scroll horizontally:

Details

Before

https://docs.python.org/3/library/random.html#examples

After

https://cpython-previews--112981.org.readthedocs.build/en/112981/library/random.html#examples

[AlexWaygood]

Thanks, this looks much better now! What do you think about doing something like this, so that all the information on subclassing random.Random is in one place?

--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -34,10 +34,8 @@ instance of the :class:`random.Random` class.  You can instantiate your own
 instances of :class:`Random` to get generators that don't share state.

 Class :class:`Random` can also be subclassed if you want to use a different
-basic generator of your own devising: in that case, override the :meth:`~Random.random`,
-:meth:`~Random.seed`, :meth:`~Random.getstate`, and :meth:`~Random.setstate` methods.
-Optionally, a new generator can supply a :meth:`~Random.getrandbits` method --- this
-allows :meth:`randrange` to produce selections over an arbitrarily large range.
+basic generator of your own devising: see the documentation on that class for
+more details.

 The :mod:`random` module also provides the :class:`SystemRandom` class which
 uses the system function :func:`os.urandom` to generate random numbers
@@ -412,6 +410,9 @@ Alternative Generator
       ``None``, :class:`int`, :class:`float`, :class:`str`,
       :class:`bytes`, or :class:`bytearray`.

+   Subclasses of :class:`!Random` should override the following methods if they
+   wish to make use of a different basic generator:
+
    .. method:: Random.seed()

       Override this method in subclasses to customise the :meth:`random.seed`
@@ -427,16 +428,21 @@ Alternative Generator
       Override this method in subclasses to customise the :meth:`random.setstate`
       behaviour of :class:`Random` instances.

-   .. method:: Random.getrandbits()
-
-      Override this method in subclasses to customise the :meth:`random.getrandbits`
-      behaviour of :class:`Random` instances.
-
    .. method:: Random.random()

       Override this method in subclasses to customise the :meth:`random.random`
       behaviour of :class:`Random` instances.

+   Optionally, a new generator can also supply the following method:
+
+   .. method:: Random.getrandbits()
+
+      Override this method in subclasses to customise the :meth:`random.getrandbits`
+      behaviour of :class:`Random` instances. This in turn allows
+      :meth:`!Random.randrange` to produce selections over an arbitrarily large
+      range.
+
+

[hugovk]

Thanks, this looks much better now! What do you think about doing something like this, so that all the information on subclassing random.Random is in one place?

Looks good, updated. Also added the missing signatures, checked against the source.

[AlexWaygood]

LGTM, thanks!

[hugovk]

Thanks all for the reviews!

[miss-islington-app]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-app]

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

[bedevere-app]

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