[3.12] Docs: Fix Sphinx warnings in io.rst (GH-107903) (#108093)

Docs: Fix Sphinx warnings in io.rst (GH-107903)

- Mark up parameter and argument names properly
- If possible, link to docs for methods like `seek`, `tell`, `write`, `read`, etc.

(cherry picked from commit 5c76899)

Co-authored-by: Erlend E. Aasland <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
Co-authored-by: T. Wouters <[email protected]>

Author: 4 people

Doc/library/io.rst

@@ -38,9 +38,9 @@ location), or only sequential access (for example in the case of a socket or
 pipe).
 
 All streams are careful about the type of data you give to them.  For example
-giving a :class:`str` object to the ``write()`` method of a binary stream
+giving a :class:`str` object to the :meth:`!write` method of a binary stream
 will raise a :exc:`TypeError`.  So will giving a :class:`bytes` object to the
-``write()`` method of a text stream.
+:meth:`!write` method of a text stream.
 
 .. versionchanged:: 3.3
    Operations that used to raise :exc:`IOError` now raise :exc:`OSError`, since
@@ -146,7 +146,7 @@ Opt-in EncodingWarning
    See :pep:`597` for more details.
 
 To find where the default locale encoding is used, you can enable
-the ``-X warn_default_encoding`` command line option or set the
+the :option:`-X warn_default_encoding <-X>` command line option or set the
 :envvar:`PYTHONWARNDEFAULTENCODING` environment variable, which will
 emit an :exc:`EncodingWarning` when the default encoding is used.
 
@@ -175,7 +175,7 @@ High-level Module Interface
    .. audit-event:: open path,mode,flags io.open
 
       This function raises an :ref:`auditing event <auditing>` ``open`` with
-      arguments ``path``, ``mode`` and ``flags``. The ``mode`` and ``flags``
+      arguments *path*, *mode* and *flags*. The *mode* and *flags*
       arguments may have been modified or inferred from the original call.
 
 
@@ -184,10 +184,10 @@ High-level Module Interface
    Opens the provided file with mode ``'rb'``. This function should be used
    when the intent is to treat the contents as executable code.
 
-   ``path`` should be a :class:`str` and an absolute path.
+   *path* should be a :class:`str` and an absolute path.
 
    The behavior of this function may be overridden by an earlier call to the
-   :c:func:`PyFile_SetOpenCodeHook`. However, assuming that ``path`` is a
+   :c:func:`PyFile_SetOpenCodeHook`. However, assuming that *path* is a
    :class:`str` and an absolute path, ``open_code(path)`` should always behave
    the same as ``open(path, 'rb')``. Overriding the behavior is intended for
    additional validation or preprocessing of the file.
@@ -258,7 +258,7 @@ standard stream implementations.
       The abstract base classes also provide default implementations of some
       methods in order to help implementation of concrete stream classes.  For
       example, :class:`BufferedIOBase` provides unoptimized implementations of
-      :meth:`~IOBase.readinto` and :meth:`~IOBase.readline`.
+      :meth:`!readinto` and :meth:`!readline`.
 
 At the top of the I/O hierarchy is the abstract base class :class:`IOBase`.  It
 defines the basic interface to a stream.  Note, however, that there is no
@@ -320,8 +320,8 @@ I/O Base Classes
    implementations represent a file that cannot be read, written or
    seeked.
 
-   Even though :class:`IOBase` does not declare :meth:`read`
-   or :meth:`write` because their signatures will vary, implementations and
+   Even though :class:`IOBase` does not declare :meth:`!read`
+   or :meth:`!write` because their signatures will vary, implementations and
    clients should consider those methods part of the interface.  Also,
    implementations may raise a :exc:`ValueError` (or :exc:`UnsupportedOperation`)
    when operations they do not support are called.
@@ -379,8 +379,8 @@ I/O Base Classes
 
    .. method:: readable()
 
-      Return ``True`` if the stream can be read from.  If ``False``, :meth:`read`
-      will raise :exc:`OSError`.
+      Return ``True`` if the stream can be read from.
+      If ``False``, :meth:`!read` will raise :exc:`OSError`.
 
    .. method:: readline(size=-1, /)
 
@@ -401,25 +401,25 @@ I/O Base Classes
       hint.
 
       Note that it's already possible to iterate on file objects using ``for
-      line in file: ...`` without calling ``file.readlines()``.
+      line in file: ...`` without calling :meth:`!file.readlines`.
 
    .. method:: seek(offset, whence=SEEK_SET, /)
 
       Change the stream position to the given byte *offset*.  *offset* is
       interpreted relative to the position indicated by *whence*.  The default
-      value for *whence* is :data:`SEEK_SET`.  Values for *whence* are:
+      value for *whence* is :data:`!SEEK_SET`.  Values for *whence* are:
 
-      * :data:`SEEK_SET` or ``0`` -- start of the stream (the default);
+      * :data:`!SEEK_SET` or ``0`` -- start of the stream (the default);
         *offset* should be zero or positive
-      * :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may
+      * :data:`!SEEK_CUR` or ``1`` -- current stream position; *offset* may
         be negative
-      * :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually
+      * :data:`!SEEK_END` or ``2`` -- end of the stream; *offset* is usually
         negative
 
       Return the new absolute position.
 
       .. versionadded:: 3.1
-         The ``SEEK_*`` constants.
+         The :data:`!SEEK_*` constants.
 
       .. versionadded:: 3.3
          Some operating systems could support additional values, like
@@ -450,7 +450,7 @@ I/O Base Classes
    .. method:: writable()
 
       Return ``True`` if the stream supports writing.  If ``False``,
-      :meth:`write` and :meth:`truncate` will raise :exc:`OSError`.
+      :meth:`!write` and :meth:`truncate` will raise :exc:`OSError`.
 
    .. method:: writelines(lines, /)
 
@@ -654,8 +654,9 @@ Raw File I/O
    implies writing, so this mode behaves in a similar way to ``'w'``. Add a
    ``'+'`` to the mode to allow simultaneous reading and writing.
 
-   The :meth:`read` (when called with a positive argument), :meth:`readinto`
-   and :meth:`write` methods on this class will only make one system call.
+   The :meth:`~RawIOBase.read` (when called with a positive argument),
+   :meth:`~RawIOBase.readinto` and :meth:`~RawIOBase.write` methods on this
+   class will only make one system call.
 
    A custom opener can be used by passing a callable as *opener*. The underlying
    file descriptor for the file object is then obtained by calling *opener* with
@@ -791,8 +792,8 @@ than raw I/O does.
    object under various conditions, including:
 
    * when the buffer gets too small for all pending data;
-   * when :meth:`flush()` is called;
-   * when a :meth:`seek()` is requested (for :class:`BufferedRandom` objects);
+   * when :meth:`flush` is called;
+   * when a :meth:`~IOBase.seek` is requested (for :class:`BufferedRandom` objects);
    * when the :class:`BufferedWriter` object is closed or destroyed.
 
    The constructor creates a :class:`BufferedWriter` for the given writeable
@@ -826,8 +827,8 @@ than raw I/O does.
    :data:`DEFAULT_BUFFER_SIZE`.
 
    :class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
-   :class:`BufferedWriter` can do.  In addition, :meth:`seek` and :meth:`tell`
-   are guaranteed to be implemented.
+   :class:`BufferedWriter` can do.  In addition, :meth:`~IOBase.seek` and
+   :meth:`~IOBase.tell` are guaranteed to be implemented.
 
 
 .. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)
@@ -904,7 +905,7 @@ Text I/O
 
    .. method:: readline(size=-1, /)
 
-      Read until newline or EOF and return a single ``str``.  If the stream is
+      Read until newline or EOF and return a single :class:`str`.  If the stream is
       already at EOF, an empty string is returned.
 
       If *size* is specified, at most *size* characters will be read.
@@ -913,22 +914,22 @@ Text I/O
 
       Change the stream position to the given *offset*.  Behaviour depends on
       the *whence* parameter.  The default value for *whence* is
-      :data:`SEEK_SET`.
+      :data:`!SEEK_SET`.
 
-      * :data:`SEEK_SET` or ``0``: seek from the start of the stream
+      * :data:`!SEEK_SET` or ``0``: seek from the start of the stream
         (the default); *offset* must either be a number returned by
         :meth:`TextIOBase.tell`, or zero.  Any other *offset* value
         produces undefined behaviour.
-      * :data:`SEEK_CUR` or ``1``: "seek" to the current position;
+      * :data:`!SEEK_CUR` or ``1``: "seek" to the current position;
         *offset* must be zero, which is a no-operation (all other values
         are unsupported).
-      * :data:`SEEK_END` or ``2``: seek to the end of the stream;
+      * :data:`!SEEK_END` or ``2``: seek to the end of the stream;
         *offset* must be zero (all other values are unsupported).
 
       Return the new absolute position as an opaque number.
 
       .. versionadded:: 3.1
-         The ``SEEK_*`` constants.
+         The :data:`!SEEK_*` constants.
 
    .. method:: tell()
 
@@ -988,10 +989,10 @@ Text I/O
      takes place.  If *newline* is any of the other legal values, any ``'\n'``
      characters written are translated to the given string.
 
-   If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
+   If *line_buffering* is ``True``, :meth:`~IOBase.flush` is implied when a call to
    write contains a newline character or a carriage return.
 
-   If *write_through* is ``True``, calls to :meth:`write` are guaranteed
+   If *write_through* is ``True``, calls to :meth:`~BufferedIOBase.write` are guaranteed
    not to be buffered: any data written on the :class:`TextIOWrapper`
    object is immediately handled to its underlying binary *buffer*.
 
@@ -1070,7 +1071,7 @@ Text I/O
 
    .. method:: getvalue()
 
-      Return a ``str`` containing the entire contents of the buffer.
+      Return a :class:`str` containing the entire contents of the buffer.
       Newlines are decoded as if by :meth:`~TextIOBase.read`, although
       the stream position is not changed.
 
@@ -1125,7 +1126,7 @@ Text I/O over a binary storage (such as a file) is significantly slower than
 binary I/O over the same storage, because it requires conversions between
 unicode and binary data using a character codec.  This can become noticeable
 handling huge amounts of text data like large log files.  Also,
-:meth:`TextIOWrapper.tell` and :meth:`TextIOWrapper.seek` are both quite slow
+:meth:`~TextIOBase.tell` and :meth:`~TextIOBase.seek` are both quite slow
 due to the reconstruction algorithm used.
 
 :class:`StringIO`, however, is a native in-memory unicode container and will
@@ -1135,7 +1136,7 @@ Multi-threading
 ^^^^^^^^^^^^^^^
 
 :class:`FileIO` objects are thread-safe to the extent that the operating system
-calls (such as ``read(2)`` under Unix) they wrap are thread-safe too.
+calls (such as :manpage:`read(2)` under Unix) they wrap are thread-safe too.
 
 Binary buffered objects (instances of :class:`BufferedReader`,
 :class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`)

Doc/tools/.nitignore

@@ -100,7 +100,6 @@ Doc/library/http.server.rst
 Doc/library/importlib.resources.rst
 Doc/library/importlib.rst
 Doc/library/inspect.rst
-Doc/library/io.rst
 Doc/library/locale.rst
 Doc/library/logging.config.rst
 Doc/library/logging.handlers.rst