From 447a15190d6d766004b77619ba43e44256e348e2 Mon Sep 17 00:00:00 2001
From: Emily Morehouse <emily@python.org>
Date: Mon, 7 Oct 2024 16:51:14 -0600
Subject: gh-125072: Add label for assignment expressions; update tracked
 section for assignment expression topic (#125074)

---
 Doc/reference/expressions.rst      |  2 ++
 Doc/tools/extensions/pyspecific.py |  4 +--
 Lib/pydoc_data/topics.py           | 64 ++++++++++++++++++++++----------------
 3 files changed, 41 insertions(+), 29 deletions(-)

diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index ab72ad4..decde0d 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -1809,6 +1809,8 @@ returns a boolean value regardless of the type of its argument
    single: named expression
    pair: assignment; expression
 
+.. _assignment-expressions:
+
 Assignment expressions
 ======================
 
diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index c89b169..b6623a2 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -353,8 +353,8 @@ class MiscNews(SphinxDirective):
 # Support for building "topic help" for pydoc
 
 pydoc_topic_labels = [
-    'assert', 'assignment', 'async', 'atom-identifiers', 'atom-literals',
-    'attribute-access', 'attribute-references', 'augassign', 'await',
+    'assert', 'assignment', 'assignment-expressions', 'async',  'atom-identifiers',
+    'atom-literals', 'attribute-access', 'attribute-references', 'augassign', 'await',
     'binary', 'bitwise', 'bltin-code-objects', 'bltin-ellipsis-object',
     'bltin-null-object', 'bltin-type-objects', 'booleans',
     'break', 'callable-types', 'calls', 'class', 'comparisons', 'compound',
diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py
index 97bb4eb..ae56c13 100644
--- a/Lib/pydoc_data/topics.py
+++ b/Lib/pydoc_data/topics.py
@@ -417,33 +417,43 @@ topics = {'assert': 'The "assert" statement\n'
                'caused a\n'
                'syntax error.\n',
  'assignment-expressions': 'Assignment expressions\n'
-          '**********************\n'
-          '\n'
-          'An assignment expression (sometimes also called a “named expression”'
-          '\nor “walrus”) assigns an expression to an identifier, while also\n'
-          'returning the value of the expression.\n'
-          '\n'
-          'One common use case is when handling matched regular expressions:\n'
-          '\n'
-          '   if matching := pattern.search(data):\n'
-          '      do_something(matching)\n'
-          '\n'
-          'Or, when processing a file stream in chunks:\n'
-          '\n'
-          '   while chunk := file.read(9000):\n'
-          '      process(chunk)\n'
-          '\n'
-          'Assignment expressions must be surrounded by parentheses when used as\n'
-          'expression statements and when used as sub-expressions in slicing,\n'
-          'conditional, lambda, keyword-argument, and comprehension-if\n'
-          'expressions and in assert, with, and assignment statements. In all\n'
-          'other places where they can be used, parentheses are not required,\n'
-          'including in if and while statements.\n'
-          '\n'
-          'Added in version 3.8.\n'
-          'See also:\n'
-          '\n'
-          '  **PEP 572** - Assignment Expressions\n',
+                           '**********************\n'
+                           '\n'
+                           '   assignment_expression ::= [identifier ":="] '
+                           'expression\n'
+                           '\n'
+                           'An assignment expression (sometimes also called a '
+                           '“named expression”\n'
+                           'or “walrus”) assigns an "expression" to an '
+                           '"identifier", while also\n'
+                           'returning the value of the "expression".\n'
+                           '\n'
+                           'One common use case is when handling matched '
+                           'regular expressions:\n'
+                           '\n'
+                           '   if matching := pattern.search(data):\n'
+                           '       do_something(matching)\n'
+                           '\n'
+                           'Or, when processing a file stream in chunks:\n'
+                           '\n'
+                           '   while chunk := file.read(9000):\n'
+                           '       process(chunk)\n'
+                           '\n'
+                           'Assignment expressions must be surrounded by '
+                           'parentheses when used as\n'
+                           'expression statements and when used as '
+                           'sub-expressions in slicing,\n'
+                           'conditional, lambda, keyword-argument, and '
+                           'comprehension-if\n'
+                           'expressions and in "assert", "with", and '
+                           '"assignment" statements. In\n'
+                           'all other places where they can be used, '
+                           'parentheses are not required,\n'
+                           'including in "if" and "while" statements.\n'
+                           '\n'
+                           'Added in version 3.8: See **PEP 572** for more '
+                           'details about\n'
+                           'assignment expressions.\n',
  'async': 'Coroutines\n'
           '**********\n'
           '\n'
-- 
cgit v0.12