gh-95975: Move except/*/finally ref labels to more precise locations (GH-95976)

* gh-95975: Move except/*/finally ref labels to more precise locations

* Add section headers to fix :keyword: role and aid navigation

* Move see also to the introduction rather than a particular subsection

* Fix other minor Sphinx syntax issues with except

Co-authored-by: Ezio Melotti <[email protected]>

* Suppress redundant link to same section for except too

* Don't link try/except/else/finally keywords if in the same section

* Format try/except/finally as keywords in modified sections

Co-authored-by: Ezio Melotti <[email protected]>
(cherry picked from commit dcc8233)

Co-authored-by: C.A.M. Gerlach <[email protected]>

Author: 2 people

Doc/reference/compound_stmts.rst

@@ -199,10 +199,8 @@ returns the list ``[0, 1, 2]``.
 .. versionchanged:: 3.11
    Starred elements are now allowed in the expression list.
 
+
 .. _try:
-.. _except:
-.. _except_star:
-.. _finally:
 
 The :keyword:`!try` statement
 =============================
@@ -215,7 +213,7 @@ The :keyword:`!try` statement
    keyword: as
    single: : (colon); compound statement
 
-The :keyword:`try` statement specifies exception handlers and/or cleanup code
+The :keyword:`!try` statement specifies exception handlers and/or cleanup code
 for a group of statements:
 
 .. productionlist:: python-grammar
@@ -231,40 +229,56 @@ for a group of statements:
    try3_stmt: "try" ":" `suite`
             : "finally" ":" `suite`
 
+Additional information on exceptions can be found in section :ref:`exceptions`,
+and information on using the :keyword:`raise` statement to generate exceptions
+may be found in section :ref:`raise`.
 
-The :keyword:`except` clause(s) specify one or more exception handlers. When no
+
+.. _except:
+
+:keyword:`!except` clause
+-------------------------
+
+The :keyword:`!except` clause(s) specify one or more exception handlers. When no
 exception occurs in the :keyword:`try` clause, no exception handler is executed.
 When an exception occurs in the :keyword:`!try` suite, a search for an exception
-handler is started.  This search inspects the except clauses in turn until one
-is found that matches the exception.  An expression-less except clause, if
-present, must be last; it matches any exception.  For an except clause with an
-expression, that expression is evaluated, and the clause matches the exception
+handler is started. This search inspects the :keyword:`!except` clauses in turn
+until one is found that matches the exception.
+An expression-less :keyword:`!except` clause, if present, must be last;
+it matches any exception.
+For an :keyword:`!except` clause with an expression,
+that expression is evaluated, and the clause matches the exception
 if the resulting object is "compatible" with the exception.  An object is
 compatible with an exception if the object is the class or a
 :term:`non-virtual base class <abstract base class>` of the exception object,
 or a tuple containing an item that is the class or a non-virtual base class
 of the exception object.
 
-If no except clause matches the exception, the search for an exception handler
+If no :keyword:`!except` clause matches the exception,
+the search for an exception handler
 continues in the surrounding code and on the invocation stack.  [#]_
 
-If the evaluation of an expression in the header of an except clause raises an
-exception, the original search for a handler is canceled and a search starts for
+If the evaluation of an expression
+in the header of an :keyword:`!except` clause raises an exception,
+the original search for a handler is canceled and a search starts for
 the new exception in the surrounding code and on the call stack (it is treated
 as if the entire :keyword:`try` statement raised the exception).
 
 .. index:: single: as; except clause
 
-When a matching except clause is found, the exception is assigned to the target
-specified after the :keyword:`!as` keyword in that except clause, if present, and
-the except clause's suite is executed.  All except clauses must have an
-executable block.  When the end of this block is reached, execution continues
-normally after the entire try statement.  (This means that if two nested
-handlers exist for the same exception, and the exception occurs in the try
-clause of the inner handler, the outer handler will not handle the exception.)
+When a matching :keyword:`!except` clause is found,
+the exception is assigned to the target
+specified after the :keyword:`!as` keyword in that :keyword:`!except` clause,
+if present, and the :keyword:`!except` clause's suite is executed.
+All :keyword:`!except` clauses must have an executable block.
+When the end of this block is reached, execution continues
+normally after the entire :keyword:`try` statement.
+(This means that if two nested handlers exist for the same exception,
+and the exception occurs in the :keyword:`!try` clause of the inner handler,
+the outer handler will not handle the exception.)
 
 When an exception has been assigned using ``as target``, it is cleared at the
-end of the except clause.  This is as if ::
+end of the :keyword:`!except` clause.  This is as if ::
 
    except E as N:
        foo
@@ -278,15 +292,17 @@ was translated to ::
            del N
 
 This means the exception must be assigned to a different name to be able to
-refer to it after the except clause.  Exceptions are cleared because with the
+refer to it after the :keyword:`!except` clause.
+Exceptions are cleared because with the
 traceback attached to them, they form a reference cycle with the stack frame,
 keeping all locals in that frame alive until the next garbage collection occurs.
 
 .. index::
    module: sys
    object: traceback
 
-Before an except clause's suite is executed, details about the exception are
+Before an :keyword:`!except` clause's suite is executed,
+details about the exception are
 stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`.
 :func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the
 exception instance and a traceback object (see section :ref:`types`) identifying
@@ -312,17 +328,24 @@ when leaving an exception handler::
    >>> print(sys.exc_info())
    (None, None, None)
 
+
 .. index::
    keyword: except_star
 
-The :keyword:`except*<except_star>` clause(s) are used for handling
-:exc:`ExceptionGroup`\ s. The exception type for matching is interpreted as in
+.. _except_star:
+
+:keyword:`!except*` clause
+--------------------------
+
+The :keyword:`!except*` clause(s) are used for handling
+:exc:`ExceptionGroup`\s. The exception type for matching is interpreted as in
 the case of :keyword:`except`, but in the case of exception groups we can have
 partial matches when the type matches some of the exceptions in the group.
-This means that multiple except* clauses can execute, each handling part of
-the exception group. Each clause executes once and handles an exception group
+This means that multiple :keyword:`!except*` clauses can execute,
+each handling part of the exception group.
+Each clause executes once and handles an exception group
 of all matching exceptions.  Each exception in the group is handled by at most
-one except* clause, the first that matches it. ::
+one :keyword:`!except*` clause, the first that matches it. ::
 
    >>> try:
    ...     raise ExceptionGroup("eg",
@@ -341,16 +364,16 @@ one except* clause, the first that matches it. ::
        | ValueError: 1
        +------------------------------------
 
-Any remaining exceptions that were not handled by any :keyword:`!except*`
-clause are re-raised at the end, combined into an exception group along with
-all exceptions that were raised from within :keyword:`!except*` clauses.
+   Any remaining exceptions that were not handled by any :keyword:`!except*`
+   clause are re-raised at the end, combined into an exception group along with
+   all exceptions that were raised from within :keyword:`!except*` clauses.
 
-An :keyword:`!except*` clause must have a matching type,
-and this type cannot be a subclass of :exc:`BaseExceptionGroup`.
-It is not possible to mix :keyword:`except` and :keyword:`!except*`
-in the same :keyword:`try`.
-:keyword:`break`, :keyword:`continue` and :keyword:`return`
-cannot appear in an :keyword:`!except*` clause.
+   An :keyword:`!except*` clause must have a matching type,
+   and this type cannot be a subclass of :exc:`BaseExceptionGroup`.
+   It is not possible to mix :keyword:`except` and :keyword:`!except*`
+   in the same :keyword:`try`.
+   :keyword:`break`, :keyword:`continue` and :keyword:`return`
+   cannot appear in an :keyword:`!except*` clause.
 
 
 .. index::
@@ -359,17 +382,28 @@ cannot appear in an :keyword:`!except*` clause.
    statement: break
    statement: continue
 
+.. _except_else:
+
+:keyword:`!else` clause
+-----------------------
+
 The optional :keyword:`!else` clause is executed if the control flow leaves the
 :keyword:`try` suite, no exception was raised, and no :keyword:`return`,
 :keyword:`continue`, or :keyword:`break` statement was executed.  Exceptions in
 the :keyword:`!else` clause are not handled by the preceding :keyword:`except`
 clauses.
 
+
 .. index:: keyword: finally
 
-If :keyword:`finally` is present, it specifies a 'cleanup' handler.  The
+.. _finally:
+
+:keyword:`!finally` clause
+--------------------------
+
+If :keyword:`!finally` is present, it specifies a 'cleanup' handler.  The
 :keyword:`try` clause is executed, including any :keyword:`except` and
-:keyword:`!else` clauses.  If an exception occurs in any of the clauses and is
+:keyword:`else` clauses.  If an exception occurs in any of the clauses and is
 not handled, the exception is temporarily saved. The :keyword:`!finally` clause
 is executed.  If there is a saved exception it is re-raised at the end of the
 :keyword:`!finally` clause.  If the :keyword:`!finally` clause raises another
@@ -387,7 +421,7 @@ or :keyword:`continue` statement, the saved exception is discarded::
    42
 
 The exception information is not available to the program during execution of
-the :keyword:`finally` clause.
+the :keyword:`!finally` clause.
 
 .. index::
    statement: return
@@ -396,10 +430,10 @@ the :keyword:`finally` clause.
 
 When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is
 executed in the :keyword:`try` suite of a :keyword:`!try`...\ :keyword:`!finally`
-statement, the :keyword:`finally` clause is also executed 'on the way out.'
+statement, the :keyword:`!finally` clause is also executed 'on the way out.'
 
 The return value of a function is determined by the last :keyword:`return`
-statement executed.  Since the :keyword:`finally` clause always executes, a
+statement executed.  Since the :keyword:`!finally` clause always executes, a
 :keyword:`!return` statement executed in the :keyword:`!finally` clause will
 always be the last one executed::
 
@@ -412,13 +446,9 @@ always be the last one executed::
    >>> foo()
    'finally'
 
-Additional information on exceptions can be found in section :ref:`exceptions`,
-and information on using the :keyword:`raise` statement to generate exceptions
-may be found in section :ref:`raise`.
-
 .. versionchanged:: 3.8
    Prior to Python 3.8, a :keyword:`continue` statement was illegal in the
-   :keyword:`finally` clause due to a problem with the implementation.
+   :keyword:`!finally` clause due to a problem with the implementation.
 
 
 .. _with: