Start on enclosures

Co-authored-by: Blaise Pabon <blaise@gmail.com>

Author: encukou

Doc/reference/expressions.rst

@@ -55,9 +55,16 @@ also categorized syntactically as atoms.  The syntax for atoms is:
 
 .. productionlist:: python-grammar
    atom: `identifier` | `literal` | `enclosure`
-   enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display`
-            : | `generator_expression` | `yield_atom`
 
+.. grammar-snippet::
+   :group: python-grammar
+
+   enclosure:
+      | (`group` | `tuple` | `yield_atom` | `generator_expression`)  # in (parentheses)
+      | `list_display`
+      | `dict_display`
+      | `set_display`
+      | `yield_atom`
 
 .. _atom-identifiers:
 
@@ -211,36 +218,75 @@ string literals::
 
 .. _parenthesized:
 
-Parenthesized forms
--------------------
+Parenthesized groups
+--------------------
 
-.. index::
-   single: parenthesized form
-   single: () (parentheses); tuple display
+A :dfn:`group` is an expression enclosed in parentheses.
+The parenthesized group evaluates to the same value as the expression inside.
 
-A parenthesized form is an optional expression list enclosed in parentheses:
+Groups are used to override or clarify
+:ref:`operator precedence <operator-precedence>`,
+in the same way as in math notation.
+For example::
 
-.. productionlist:: python-grammar
-   parenth_form: "(" [`starred_expression`] ")"
+   >>> 3 + 2 * 4
+   11
+   >>> (3 + 2) * 4    # Override precedence of the addition
+   20
+   >>> 3 + (2 * 4)    # Same effect as without parentheses
+   11
+
+   >>> 3 << 2 | 4
+   12
+   >>> 3 << (2 | 4)   # Override precedence of the bitwise OR
+   192
+   >>> (3 << 2) | 4   # Same as without parentheses, but much clearer
+   12
 
-A parenthesized expression list yields whatever that expression list yields: if
-the list contains at least one comma, it yields a tuple; otherwise, it yields
-the single expression that makes up the expression list.
+Formally, the syntax for groups is:
 
-.. index:: pair: empty; tuple
+.. grammar-snippet::
+   :group: python-grammar
 
-An empty pair of parentheses yields an empty tuple object.  Since tuples are
-immutable, the same rules as for literals apply (i.e., two occurrences of the empty
-tuple may or may not yield the same object).
+   group: '(' `assignment_expression` ')'
 
-.. index::
-   single: comma
-   single: , (comma)
 
-Note that tuples are not formed by the parentheses, but rather by use of the
-comma.  The exception is the empty tuple, for which parentheses *are*
-required --- allowing unparenthesized "nothing" in expressions would cause
-ambiguities and allow common typos to pass uncaught.
+
+Tuple displays
+--------------
+
+..
+
+         Parenthesized forms
+         -------------------
+
+         .. index::
+            single: parenthesized form
+            single: () (parentheses); tuple display
+
+         A parenthesized form is an optional expression list enclosed in parentheses:
+
+         .. productionlist:: python-grammar
+            parenth_form: "(" [`starred_expression`] ")"
+
+         A parenthesized expression list yields whatever that expression list yields: if
+         the list contains at least one comma, it yields a tuple; otherwise, it yields
+         the single expression that makes up the expression list.
+
+         .. index:: pair: empty; tuple
+
+         An empty pair of parentheses yields an empty tuple object.  Since tuples are
+         immutable, the same rules as for literals apply (i.e., two occurrences of the empty
+         tuple may or may not yield the same object).
+
+         .. index::
+            single: comma
+            single: , (comma)
+
+         Note that tuples are not formed by the parentheses, but rather by use of the
+         comma.  The exception is the empty tuple, for which parentheses *are*
+         required --- allowing unparenthesized "nothing" in expressions would cause
+         ambiguities and allow common typos to pass uncaught.
 
 
 .. _comprehensions:
@@ -2049,6 +2095,7 @@ their suffixes::
 
 
 .. _operator-summary:
+.. _operator-precedence:
 
 Operator precedence
 ===================

Doc/reference/introduction.rst

@@ -145,6 +145,8 @@ The definition to the right of the colon uses the following syntax elements:
 * ``e?``: A question mark has exactly the same meaning as square brackets:
   the preceding item is optional.
 * ``(e)``: Parentheses are used for grouping.
+* ``# ...``: As in Python, ``#`` introduces a comment that continues until the
+  end of the line.
 
 The following notation is only used in
 :ref:`lexical definitions <notation-lexical-vs-syntactic>`.

Doc/tools/extensions/grammar_snippet.py

@@ -36,6 +36,21 @@ def __init__(
         self['classes'].append('sx')
 
 
+class snippet_comment_node(nodes.inline):  # noqa: N801 (snake_case is fine)
+    """Node for a comment in a grammar snippet."""
+
+    def __init__(
+        self,
+        rawsource: str = '',
+        text: str = '',
+        *children: Node,
+        **attributes: Any,
+    ) -> None:
+        super().__init__(rawsource, text, *children, **attributes)
+        # Use the Pygments highlight class for `Comment.Single`
+        self['classes'].append('c1')
+
+
 class GrammarSnippetBase(SphinxDirective):
     """Common functionality for GrammarSnippetDirective & CompatProductionList."""
 
@@ -51,6 +66,8 @@ class GrammarSnippetBase(SphinxDirective):
             (?P<single_quoted>'[^']*')        # string in 'quotes'
         |
             (?P<double_quoted>"[^"]*")        # string in "quotes"
+        |
+            (?P<comment>[#].*)                # comment
         """,
         re.VERBOSE,
     )
@@ -147,6 +164,8 @@ def make_production(
                     production_node += token_xrefs(content, group_name)
                 case 'single_quoted' | 'double_quoted':
                     production_node += snippet_string_node('', content)
+                case 'comment':
+                    production_node += snippet_comment_node('', content)
                 case 'text':
                     production_node += nodes.Text(content)
                 case _: