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

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

Co-authored-by: Alex Waygood <[email protected]>

Author: miss-islington

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
 ----------
 

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.

Doc/tools/.nitignore

@@ -82,7 +82,6 @@ Doc/library/pyexpat.rst
 Doc/library/random.rst
 Doc/library/readline.rst
 Doc/library/resource.rst
-Doc/library/rlcompleter.rst
 Doc/library/select.rst
 Doc/library/signal.rst
 Doc/library/smtplib.rst