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

[erlend-aasland]

https://github.com/python/cpython/commit/9a70989a6f5f3f9d6fd36de002dab0ab1e13a9e3
commit: 9a70989a6f5f3f9d6fd36de002dab0ab1e13a9e3
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-08-18T10:25:08Z
summary:

[3.11] Docs: emphasise warning and add accurate markups for sys.unraisablehook (GH-108105) (#108110)

(cherry picked from commit cc58ec9724772a8d5c4a5c9a6525f9f96e994227)

Co-authored-by: Erlend E. Aasland <erlend at python.org>

files:
M Doc/library/sys.rst

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 641be05a16fb3..b5ad0b6860b95 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1747,35 +1747,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