[3.12] gh-101100: Fix Sphinx nitpicks in `library/rlcompleter.rst` (GH-113125) (#113158)

gh-101100: Fix Sphinx nitpicks in `library/rlcompleter.rst` (GH-113125)
(cherry picked from commit 7bb00f053e0a86bb8827cc464961a4fad9278e6d)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

2 files changed, 24 insertions, 18 deletions

diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst
index 8fb0eca..3cd3593 100644
--- a/Doc/library/readline.rst
+++ b/Doc/library/readline.rst
@@ -213,6 +213,8 @@ Startup hooks
    if Python was compiled for a version of the library that supports it.
 
 
+.. _readline-completion:
+
 Completion
 ----------
 
diff --git a/Doc/library/rlcompleter.rst b/Doc/library/rlcompleter.rst
index 40b09ce..8287699 100644
--- a/Doc/library/rlcompleter.rst
+++ b/Doc/library/rlcompleter.rst
@@ -10,12 +10,14 @@
 
 --------------
 
-The :mod:`rlcompleter` module defines a completion function suitable for the
-:mod:`readline` module by completing valid Python identifiers and keywords.
+The :mod:`!rlcompleter` module defines a completion function suitable to be
+passed to :func:`~readline.set_completer` in the :mod:`readline` module.
 
 When this module is imported on a Unix platform with the :mod:`readline` module
 available, an instance of the :class:`Completer` class is automatically created
-and its :meth:`complete` method is set as the :mod:`readline` completer.
+and its :meth:`~Completer.complete` method is set as the
+:ref:`readline completer <readline-completion>`. The method provides
+completion of valid Python :ref:`identifiers and keywords <identifiers>`.
 
 Example::
 
@@ -28,7 +30,7 @@ Example::
    readline.__name__         readline.parse_and_bind(
    >>> readline.
 
-The :mod:`rlcompleter` module is designed for use with Python's
+The :mod:`!rlcompleter` module is designed for use with Python's
 :ref:`interactive mode <tut-interactive>`.  Unless Python is run with the
 :option:`-S` option, the module is automatically imported and configured
 (see :ref:`rlcompleter-config`).
@@ -39,23 +41,25 @@ this module can still be used for custom purposes.
 
 .. _completer-objects:
 
-Completer Objects
------------------
+.. class:: Completer
 
-Completer objects have the following method:
+   Completer objects have the following method:
 
+   .. method:: Completer.complete(text, state)
 
-.. method:: Completer.complete(text, state)
+      Return the next possible completion for *text*.
 
-   Return the *state*\ th completion for *text*.
+      When called by the :mod:`readline` module, this method is called
+      successively with ``state == 0, 1, 2, ...`` until the method returns
+      ``None``.
 
-   If called for *text* that doesn't include a period character (``'.'``), it will
-   complete from names currently defined in :mod:`__main__`, :mod:`builtins` and
-   keywords (as defined by the :mod:`keyword` module).
-
-   If called for a dotted name, it will try to evaluate anything without obvious
-   side-effects (functions will not be evaluated, but it can generate calls to
-   :meth:`__getattr__`) up to the last part, and find matches for the rest via the
-   :func:`dir` function.  Any exception raised during the evaluation of the
-   expression is caught, silenced and :const:`None` is returned.
+      If called for *text* that doesn't include a period character (``'.'``), it will
+      complete from names currently defined in :mod:`__main__`, :mod:`builtins` and
+      keywords (as defined by the :mod:`keyword` module).
 
+      If called for a dotted name, it will try to evaluate anything without obvious
+      side-effects (functions will not be evaluated, but it can generate calls to
+      :meth:`~object.__getattr__`) up to the last part, and find matches for the
+      rest via the :func:`dir` function.  Any exception raised during the
+      evaluation of the expression is caught, silenced and :const:`None` is
+      returned.