bpo-45640: [docs] Tokens are now clickable (GH-29260) (GH-29621)
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
(cherry picked from commit 32959108f9c543e3cb9f2b68bbc782bddded6f42)
Co-authored-by: Arthur Milchior <arthur@milchior.fr>
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index ab47f37..c3f58fc 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -445,21 +445,20 @@
:ref:`asynchronous-generator-functions`.
When a generator function is called, it returns an iterator known as a
-generator. That generator then controls the execution of the generator function.
-The execution starts when one of the generator's methods is called. At that
-time, the execution proceeds to the first yield expression, where it is
-suspended again, returning the value of :token:`expression_list` to the generator's
-caller. By suspended, we mean that all local state is retained, including the
-current bindings of local variables, the instruction pointer, the internal
-evaluation stack, and the state of any exception handling. When the execution
-is resumed by calling one of the
-generator's methods, the function can proceed exactly as if the yield expression
-were just another external call. The value of the yield expression after
-resuming depends on the method which resumed the execution. If
-:meth:`~generator.__next__` is used (typically via either a :keyword:`for` or
-the :func:`next` builtin) then the result is :const:`None`. Otherwise, if
-:meth:`~generator.send` is used, then the result will be the value passed in to
-that method.
+generator. That generator then controls the execution of the generator
+function. The execution starts when one of the generator's methods is called.
+At that time, the execution proceeds to the first yield expression, where it is
+suspended again, returning the value of :token:`~python-grammar:expression_list`
+to the generator's caller. By suspended, we mean that all local state is
+retained, including the current bindings of local variables, the instruction
+pointer, the internal evaluation stack, and the state of any exception handling.
+When the execution is resumed by calling one of the generator's methods, the
+function can proceed exactly as if the yield expression were just another
+external call. The value of the yield expression after resuming depends on the
+method which resumed the execution. If :meth:`~generator.__next__` is used
+(typically via either a :keyword:`for` or the :func:`next` builtin) then the
+result is :const:`None`. Otherwise, if :meth:`~generator.send` is used, then
+the result will be the value passed in to that method.
.. index:: single: coroutine
@@ -509,8 +508,8 @@
usable as simple coroutines.
:pep:`380` - Syntax for Delegating to a Subgenerator
- The proposal to introduce the :token:`yield_from` syntax, making delegation
- to subgenerators easy.
+ The proposal to introduce the :token:`~python-grammar:yield_from` syntax,
+ making delegation to subgenerators easy.
:pep:`525` - Asynchronous Generators
The proposal that expanded on :pep:`492` by adding generator capabilities to
@@ -538,9 +537,9 @@
:meth:`~generator.__next__` method, the current yield expression always
evaluates to :const:`None`. The execution then continues to the next yield
expression, where the generator is suspended again, and the value of the
- :token:`expression_list` is returned to :meth:`__next__`'s caller. If the
- generator exits without yielding another value, a :exc:`StopIteration`
- exception is raised.
+ :token:`~python-grammar:expression_list` is returned to :meth:`__next__`'s
+ caller. If the generator exits without yielding another value, a
+ :exc:`StopIteration` exception is raised.
This method is normally called implicitly, e.g. by a :keyword:`for` loop, or
by the built-in :func:`next` function.
@@ -629,21 +628,20 @@
:keyword:`async for` statement in a coroutine function analogously to
how a generator object would be used in a :keyword:`for` statement.
-Calling one of the asynchronous generator's methods returns an
-:term:`awaitable` object, and the execution starts when this object
-is awaited on. At that time, the execution proceeds to the first yield
-expression, where it is suspended again, returning the value of
-:token:`expression_list` to the awaiting coroutine. As with a generator,
-suspension means that all local state is retained, including the
-current bindings of local variables, the instruction pointer, the internal
-evaluation stack, and the state of any exception handling. When the execution
-is resumed by awaiting on the next object returned by the asynchronous
-generator's methods, the function can proceed exactly as if the yield
-expression were just another external call. The value of the yield expression
-after resuming depends on the method which resumed the execution. If
+Calling one of the asynchronous generator's methods returns an :term:`awaitable`
+object, and the execution starts when this object is awaited on. At that time,
+the execution proceeds to the first yield expression, where it is suspended
+again, returning the value of :token:`~python-grammar:expression_list` to the
+awaiting coroutine. As with a generator, suspension means that all local state
+is retained, including the current bindings of local variables, the instruction
+pointer, the internal evaluation stack, and the state of any exception handling.
+When the execution is resumed by awaiting on the next object returned by the
+asynchronous generator's methods, the function can proceed exactly as if the
+yield expression were just another external call. The value of the yield
+expression after resuming depends on the method which resumed the execution. If
:meth:`~agen.__anext__` is used then the result is :const:`None`. Otherwise, if
-:meth:`~agen.asend` is used, then the result will be the value passed in to
-that method.
+:meth:`~agen.asend` is used, then the result will be the value passed in to that
+method.
If an asynchronous generator happens to exit early by :keyword:`break`, the caller
task being cancelled, or other exceptions, the generator's async cleanup code
@@ -695,10 +693,10 @@
Returns an awaitable which when run starts to execute the asynchronous
generator or resumes it at the last executed yield expression. When an
asynchronous generator function is resumed with an :meth:`~agen.__anext__`
- method, the current yield expression always evaluates to :const:`None` in
- the returned awaitable, which when run will continue to the next yield
- expression. The value of the :token:`expression_list` of the yield
- expression is the value of the :exc:`StopIteration` exception raised by
+ method, the current yield expression always evaluates to :const:`None` in the
+ returned awaitable, which when run will continue to the next yield
+ expression. The value of the :token:`~python-grammar:expression_list` of the
+ yield expression is the value of the :exc:`StopIteration` exception raised by
the completing coroutine. If the asynchronous generator exits without
yielding another value, the awaitable instead raises a
:exc:`StopAsyncIteration` exception, signalling that the asynchronous
@@ -1699,8 +1697,9 @@
assignment_expression: [`identifier` ":="] `expression`
An assignment expression (sometimes also called a "named expression" or
-"walrus") assigns an :token:`expression` to an :token:`identifier`, while also
-returning the value of the :token:`expression`.
+"walrus") assigns an :token:`~python-grammar:expression` to an
+:token:`~python-grammar:identifier`, while also returning the value of the
+:token:`~python-grammar:expression`.
One common use case is when handling matched regular expressions: