gh-101100: Fix Sphinx nitpicks in `library/rlcompleter.rst` (#113125)

diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst
index 2e0f45ced30b9cdc0dee881301de0d9a52d610ce..1adafcaa02eab9710b2930b91b9801ce156d56dc 100644 (file)
--- a/Doc/library/readline.rst
+++ b/Doc/library/readline.rst
@@ -218,6 +218,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 40b09ce897880edd450c99fef939d8f5fed55028..8287699c5f013ec5d148a749f4a5f249cb9ea6eb 100644 (file)
--- 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.

diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index d9147aaeee12bd6e5e65607c0b1b6ae2739396c1..c91e698ff0753a1352741299b73ba7c3649359cc 100644 (file)
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -79,7 +79,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