[3.14] gh-101100: Fix sphinx warnings in `library/smtplib.rst` (GH-139991) (#140084)

Co-authored-by: Weilin Du <108666168+LamentXU123@users.noreply.github.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index c5f8516f768a68bb91bbfb5b5aa4dcc87f520404..c5a3de52090cee758a79551f352dbfc7ed18ce6b 100644 (file)
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -80,8 +80,8 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
 
    An :class:`SMTP_SSL` instance behaves exactly the same as instances of
    :class:`SMTP`. :class:`SMTP_SSL` should be used for situations where SSL is
-   required from the beginning of the connection and using :meth:`starttls` is
-   not appropriate. If *host* is not specified, the local host is used. If
+   required from the beginning of the connection and using :meth:`~SMTP.starttls`
+   is not appropriate. If *host* is not specified, the local host is used. If
    *port* is zero, the standard SMTP-over-SSL port (465) is used.  The optional
    arguments *local_hostname*, *timeout* and *source_address* have the same
    meaning as they do in the :class:`SMTP` class.  *context*, also optional,
@@ -112,7 +112,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
 
    The LMTP protocol, which is very similar to ESMTP, is heavily based on the
    standard SMTP client. It's common to use Unix sockets for LMTP, so our
-   :meth:`connect` method must support that as well as a regular host:port
+   :meth:`~SMTP.connect` method must support that as well as a regular host:port
    server. The optional arguments *local_hostname* and *source_address* have the
    same meaning as they do in the :class:`SMTP` class. To specify a Unix
    socket, you must use an absolute path for *host*, starting with a '/'.
@@ -147,9 +147,15 @@ A nice selection of exceptions is defined as well:
 .. exception:: SMTPResponseException
 
    Base class for all exceptions that include an SMTP error code. These exceptions
-   are generated in some instances when the SMTP server returns an error code.  The
-   error code is stored in the :attr:`smtp_code` attribute of the error, and the
-   :attr:`smtp_error` attribute is set to the error message.
+   are generated in some instances when the SMTP server returns an error code.
+
+   .. attribute:: smtp_code
+
+      The error code.
+
+   .. attribute:: smtp_error
+
+      The error message.
 
 
 .. exception:: SMTPSenderRefused
@@ -161,9 +167,13 @@ A nice selection of exceptions is defined as well:
 
 .. exception:: SMTPRecipientsRefused
 
-   All recipient addresses refused.  The errors for each recipient are accessible
-   through the attribute :attr:`recipients`, which is a dictionary of exactly the
-   same sort as :meth:`SMTP.sendmail` returns.
+   All recipient addresses refused.
+
+   .. attribute:: recipients
+
+      A dictionary of exactly the same sort as returned
+      by :meth:`SMTP.sendmail` containing the errors for
+      each recipient.
 
 
 .. exception:: SMTPDataError
@@ -213,7 +223,6 @@ SMTP Objects
 
 An :class:`SMTP` instance has the following methods:
 
-
 .. method:: SMTP.set_debuglevel(level)
 
    Set the debug output level.  A value of 1 or ``True`` for *level* results in
@@ -417,7 +426,7 @@ An :class:`SMTP` instance has the following methods:
 
    .. versionchanged:: 3.4
       The method now supports hostname check with
-      :attr:`SSLContext.check_hostname` and *Server Name Indicator* (see
+      :attr:`ssl.SSLContext.check_hostname` and *Server Name Indicator* (see
       :const:`~ssl.HAS_SNI`).
 
    .. versionchanged:: 3.5
@@ -435,7 +444,7 @@ An :class:`SMTP` instance has the following methods:
    ESMTP options (such as ``DSN`` commands) that should be used with all ``RCPT``
    commands can be passed as *rcpt_options*.  (If you need to use different ESMTP
    options to different recipients you have to use the low-level methods such as
-   :meth:`mail`, :meth:`rcpt` and :meth:`data` to send the message.)
+   :meth:`!mail`, :meth:`!rcpt` and :meth:`!data` to send the message.)
 
    .. note::
 
@@ -467,10 +476,7 @@ An :class:`SMTP` instance has the following methods:
    This method may raise the following exceptions:
 
    :exc:`SMTPRecipientsRefused`
-      All recipients were refused.  Nobody got the mail.  The :attr:`recipients`
-      attribute of the exception object is a dictionary with information about the
-      refused recipients (like the one returned when at least one recipient was
-      accepted).
+      All recipients were refused.  Nobody got the mail.
 
    :exc:`SMTPHeloError`
       The server didn't reply properly to the ``HELO`` greeting.
@@ -546,6 +552,30 @@ Low-level methods corresponding to the standard SMTP/ESMTP commands ``HELP``,
 Normally these do not need to be called directly, so they are not documented
 here.  For details, consult the module code.
 
+Additionally, an SMTP instance has the following attributes:
+
+
+.. attribute:: SMTP.helo_resp
+
+   The response to the ``HELO`` command, see :meth:`helo`.
+
+
+.. attribute:: SMTP.ehlo_resp
+
+   The response to the ``EHLO`` command, see :meth:`ehlo`.
+
+
+.. attribute:: SMTP.does_esmtp
+
+   A boolean value indicating whether the server supports ESMTP, see
+   :meth:`ehlo`.
+
+
+.. attribute:: SMTP.esmtp_features
+
+   A dictionary of the names of SMTP service extensions supported by the server,
+   see :meth:`ehlo`.
+
 
 .. _smtp-example:
 

diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index 60a80fe2c72a724b5980c61c556bfea0c4482b76..29fd3cfda458f0dfd8c36f5678c6fa9160055254 100644 (file)
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -29,7 +29,6 @@ Doc/library/profile.rst
 Doc/library/pyexpat.rst
 Doc/library/resource.rst
 Doc/library/select.rst
-Doc/library/smtplib.rst
 Doc/library/socket.rst
 Doc/library/ssl.rst
 Doc/library/stdtypes.rst