bpo-35563: Add reference links to warnings.rst (GH-11289)

csabella · web-flow · commit 6220c02e09e9 · 2019-05-20T18:45:05.000-04:00
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
@@ -19,10 +19,10 @@ Python programmers issue warnings by calling the :func:`warn` function defined
 in this module.  (C programmers use :c:func:`PyErr_WarnEx`; see
 :ref:`exceptionhandling` for details).
 
-Warning messages are normally written to ``sys.stderr``, but their disposition
+Warning messages are normally written to :data:`sys.stderr`, but their disposition
 can be changed flexibly, from ignoring all warnings to turning them into
-exceptions.  The disposition of warnings can vary based on the warning category
-(see below), the text of the warning message, and the source location where it
+exceptions.  The disposition of warnings can vary based on the :ref:`warning category
+<warning-categories>`, the text of the warning message, and the source location where it
 is issued.  Repetitions of a particular warning for the same source location are
 typically suppressed.
 
@@ -31,7 +31,7 @@ determination is made whether a message should be issued or not; next, if a
 message is to be issued, it is formatted and printed using a user-settable hook.
 
 The determination whether to issue a warning message is controlled by the
-warning filter, which is a sequence of matching rules and actions. Rules can be
+:ref:`warning filter <warning-filter>`, which is a sequence of matching rules and actions. Rules can be
 added to the filter by calling :func:`filterwarnings` and reset to its default
 state by calling :func:`resetwarnings`.
 
@@ -181,9 +181,9 @@ Describing Warning Filters
 The warnings filter is initialized by :option:`-W` options passed to the Python
 interpreter command line and the :envvar:`PYTHONWARNINGS` environment variable.
 The interpreter saves the arguments for all supplied entries without
-interpretation in ``sys.warnoptions``; the :mod:`warnings` module parses these
+interpretation in :data:`sys.warnoptions`; the :mod:`warnings` module parses these
 when it is first imported (invalid options are ignored, after printing a
-message to ``sys.stderr``).
+message to :data:`sys.stderr`).
 
 Individual warnings filters are specified as a sequence of fields separated by
 colons::
@@ -192,7 +192,7 @@ colons::
 
 The meaning of each of these fields is as described in :ref:`warning-filter`.
 When listing multiple filters on a single line (as for
-:envvar:`PYTHONWARNINGS`), the individual filters are separated by commas,and
+:envvar:`PYTHONWARNINGS`), the individual filters are separated by commas and
 the filters listed later take precedence over those listed before them (as
 they're applied left-to-right, and the most recently applied filters take
 precedence over earlier ones).
@@ -395,12 +395,12 @@ Available Functions
 .. function:: warn(message, category=None, stacklevel=1, source=None)
 
    Issue a warning, or maybe ignore it or raise an exception.  The *category*
-   argument, if given, must be a warning category class (see above); it defaults to
-   :exc:`UserWarning`.  Alternatively *message* can be a :exc:`Warning` instance,
+   argument, if given, must be a :ref:`warning category class <warning-categories>`; it
+   defaults to :exc:`UserWarning`.  Alternatively, *message* can be a :exc:`Warning` instance,
    in which case *category* will be ignored and ``message.__class__`` will be used.
-   In this case the message text will be ``str(message)``. This function raises an
+   In this case, the message text will be ``str(message)``. This function raises an
    exception if the particular warning issued is changed into an error by the
-   warnings filter see above.  The *stacklevel* argument can be used by wrapper
+   :ref:`warnings filter <warning-filter>`.  The *stacklevel* argument can be used by wrapper
    functions written in Python, like this::
 
       def deprecation(message):
@@ -444,7 +444,7 @@ Available Functions
 
    Write a warning to a file.  The default implementation calls
    ``formatwarning(message, category, filename, lineno, line)`` and writes the
-   resulting string to *file*, which defaults to ``sys.stderr``.  You may replace
+   resulting string to *file*, which defaults to :data:`sys.stderr`.  You may replace
    this function with any callable by assigning to ``warnings.showwarning``.
    *line* is a line of source code to be included in the warning
    message; if *line* is not supplied, :func:`showwarning` will
