[Python-checkins] Docs: emphasise warning and add accurate markups for sys.unraisablehook (#108105)

[erlend-aasland]

https://github.com/python/cpython/commit/cc58ec9724772a8d5c4a5c9a6525f9f96e994227
commit: cc58ec9724772a8d5c4a5c9a6525f9f96e994227
branch: main
author: Erlend E. Aasland <erlend at python.org>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-08-18T12:16:22+02:00
summary:

Docs: emphasise warning and add accurate markups for sys.unraisablehook (#108105)

files:
M Doc/library/sys.rst

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 33391d11ab392..b6346bafbf625 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1811,35 +1811,39 @@ always available.
 
    The *unraisable* argument has the following attributes:
 
-   * *exc_type*: Exception type.
-   * *exc_value*: Exception value, can be ``None``.
-   * *exc_traceback*: Exception traceback, can be ``None``.
-   * *err_msg*: Error message, can be ``None``.
-   * *object*: Object causing the exception, can be ``None``.
+   * :attr:`!exc_type`: Exception type.
+   * :attr:`!exc_value`: Exception value, can be ``None``.
+   * :attr:`!exc_traceback`: Exception traceback, can be ``None``.
+   * :attr:`!err_msg`: Error message, can be ``None``.
+   * :attr:`!object`: Object causing the exception, can be ``None``.
 
-   The default hook formats *err_msg* and *object* as:
+   The default hook formats :attr:`!err_msg` and :attr:`!object` as:
    ``f'{err_msg}: {object!r}'``; use "Exception ignored in" error message
-   if *err_msg* is ``None``.
+   if :attr:`!err_msg` is ``None``.
 
    :func:`sys.unraisablehook` can be overridden to control how unraisable
    exceptions are handled.
 
-   Storing *exc_value* using a custom hook can create a reference cycle. It
-   should be cleared explicitly to break the reference cycle when the
-   exception is no longer needed.
+   .. seealso::
+
+      :func:`excepthook` which handles uncaught exceptions.
+
+   .. warning::
 
-   Storing *object* using a custom hook can resurrect it if it is set to an
-   object which is being finalized. Avoid storing *object* after the custom
-   hook completes to avoid resurrecting objects.
+      Storing :attr:`!exc_value` using a custom hook can create a reference cycle.
+      It should be cleared explicitly to break the reference cycle when the
+      exception is no longer needed.
 
-   See also :func:`excepthook` which handles uncaught exceptions.
+      Storing :attr:`!object` using a custom hook can resurrect it if it is set to an
+      object which is being finalized. Avoid storing :attr:`!object` after the custom
+      hook completes to avoid resurrecting objects.
 
    .. audit-event:: sys.unraisablehook hook,unraisable sys.unraisablehook
 
       Raise an auditing event ``sys.unraisablehook`` with arguments
-      ``hook``, ``unraisable`` when an exception that cannot be handled occurs.
-      The ``unraisable`` object is the same as what will be passed to the hook.
-      If no hook has been set, ``hook`` may be ``None``.
+      *hook*, *unraisable* when an exception that cannot be handled occurs.
+      The *unraisable* object is the same as what will be passed to the hook.
+      If no hook has been set, *hook* may be ``None``.
 
    .. versionadded:: 3.8