8000 bpo-41762: Fix usage of productionlist markup in the doc (GH-22281) · python/cpython@c053402 · GitHub
[go: up one dir, main page]

Skip to content

Commit c053402

Browse files
bpo-41762: Fix usage of productionlist markup in the doc (GH-22281)
Use an unique identifier for the different grammars documented using the Sphinx productionlist markup. productionlist markups of the same grammar, like "expressions" or "compound statements", use the same identifier "python-grammar". (cherry picked from commit 8af239e) Co-authored-by: Victor Stinner <vstinner@python.org>
1 parent 6d893ba commit c053402

File tree

8 files changed

+70
-69
lines changed

8 files changed

+70
-69
lines changed

Doc/library/functions.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -582,7 +582,7 @@ are always available. They are listed here in alphabetical order.
582582
input must conform to the following grammar after leading and trailing
583583
whitespace characters are removed:
584584

585-
.. productionlist::
585+
.. productionlist:: float
586586
sign: "+" | "-"
587587
infinity: "Infinity" | "inf"
588588
nan: "nan"

Doc/library/string.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``.
205205

206206
The grammar for a replacement field is as follows:
207207

208-
.. productionlist:: sf
208+
.. productionlist:: format-string
209209
replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
210210
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
211211
arg_name: [`identifier` | `digit`+]
@@ -308,7 +308,7 @@ non-empty format specification typically modifies the result.
308308

309309
The general form of a *standard format specifier* is:
310310

311-
.. productionlist::
311+
.. productionlist:: format-spec
312312
format_spec: [[`fill`]`align`][`sign`][#][0][`width`][`grouping_option`][.`precision`][`type`]
313313
fill: <any character>
314314
align: "<" | ">" | "=" | "^"

Doc/reference/compound_stmts.rst

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,8 @@ executed::
4444

4545
Summarizing:
4646

47-
.. productionlist::
47+
48+
.. productionlist:: python-grammar
4849
compound_stmt: `if_stmt`
4950
: | `while_stmt`
5051
: | `for_stmt`
@@ -89,7 +90,7 @@ The :keyword:`!if` statement
8990

9091
The :keyword:`if` statement is used for conditional execution:
9192

92-
.. productionlist::
93+
.. productionlist:: python-grammar
9394
if_stmt: "if" `assignment_expression` ":" `suite`
9495
: ("elif" `assignment_expression` ":" `suite`)*
9596
: ["else" ":" `suite`]
@@ -115,7 +116,7 @@ The :keyword:`!while` statement
115116
The :keyword:`while` statement is used for repeated execution as long as an
116117
expression is true:
117118

118-
.. productionlist::
119+
.. productionlist:: python-grammar
119120
while_stmt: "while" `assignment_expression` ":" `suite`
120121
: ["else" ":" `suite`]
121122

@@ -151,7 +152,7 @@ The :keyword:`!for` statement
151152
The :keyword:`for` statement is used to iterate over the elements of a sequence
152153
(such as a string, tuple or list) or other iterable object:
153154

154-
.. productionlist::
155+
.. productionlist:: python-grammar
155156
for_stmt: "for" `target_list` "in" `expression_list` ":" `suite`
156157
: ["else" ":" `suite`]
157158

@@ -234,7 +235,7 @@ The :keyword:`!try` statement
234235
The :keyword:`try` statement specifies exception handlers and/or cleanup code
235236
for a group of statements:
236237

237-
.. productionlist::
238+
.. productionlist:: python-grammar
238239
try_stmt: `try1_stmt` | `try2_stmt`
239240
try1_stmt: "try" ":" `suite`
240241
: ("except" [`expression` ["as" `identifier`]] ":" `suite`)+
@@ -390,7 +391,7 @@ methods defined by a context manager (see section :ref:`context-managers`).
390391
This allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally`
391392
usage patterns to be encapsulated for convenient reuse.
392393

393-
.. productionlist::
394+
.. productionlist:: python-grammar
394395
with_stmt: "with" `with_item` ("," `with_item`)* ":" `suite`
395396
with_item: `expression` ["as" `target`]
396397

@@ -503,7 +504,7 @@ Function definitions
503504
A function definition defines a user-defined function object (see section
504505
:ref:`types`):
505506

506-
.. productionlist::
507+
.. productionlist:: python-grammar
507508
funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")"
508509
: ["->" `expression`] ":" `suite`
509510
decorators: `decorator`+
@@ -670,7 +671,7 @@ Class definitions
670671

671672
A class definition defines a class object (see section :ref:`types`):
672673

673-
.. productionlist::
674+
.. productionlist:: python-grammar
674675
classdef: [`decorators`] "class" `classname` [`inheritance`] ":" `suite`
675676
inheritance: "(" [`argument_list`] ")"
676677
classname: `identifier`
@@ -762,7 +763,7 @@ Coroutines
762763
Coroutine function definition
763764
-----------------------------
764765

765-
.. productionlist::
766+
.. productionlist:: python-grammar
766767
async_funcdef: [`decorators`] "async" "def" `funcname` "(" [`parameter_list`] ")"
767768
: ["->" `expression`] ":" `suite`
768769

@@ -795,7 +796,7 @@ An example of a coroutine function::
795796
The :keyword:`!async for` statement
796797
-----------------------------------
797798

798-
.. productionlist::
799+
.. productionlist:: python-grammar
799800
async_for_stmt: "async" `for_stmt`
800801

801802
An :term:`asynchronous iterable` is able to call asynchronous code in its
@@ -840,7 +841,7 @@ body of a coroutine function.
840841
The :keyword:`!async with` statement
841842
------------------------------------
842843

843-
.. productionlist::
844+
.. productionlist:: python-grammar
844845
async_with_stmt: "async" `with_stmt`
845846

846847
An :term:`asynchronous context manager` is a :term:`context manager` that is

Doc/reference/expressions.rst

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ This chapter explains the meaning of the elements of expressions in Python.
1313
be used to describe syntax, not lexical analysis. When (one alternative of) a
1414
syntax rule has the form
1515

16-
.. productionlist:: *
16+
.. productionlist:: python-grammar
1717
name: `othername`
1818

1919
and no semantics are given, the semantics of this form of ``name`` are the same
@@ -54,7 +54,7 @@ Atoms are the most basic elements of expressions. The simplest atoms are
5454
identifiers or literals. Forms enclosed in parentheses, brackets or braces are
5555
also categorized syntactically as atoms. The syntax for atoms is:
5656

57-
.. productionlist::
57+
.. productionlist:: python-grammar
5858
atom: `identifier` | `literal` | `enclosure`
5959
enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display`
6060
: | `generator_expression` | `yield_atom`
@@ -103,7 +103,7 @@ Literals
103103

104104
Python supports string and bytes literals and various numeric literals:
105105

106-
.. productionlist::
106+
.. productionlist:: python-grammar
107107
literal: `stringliteral` | `bytesliteral`
108108
: | `integer` | `floatnumber` | `imagnumber`
109109

@@ -134,7 +134,7 @@ Parenthesized forms
134134

135135
A parenthesized form is an optional expression list enclosed in parentheses:
136136

137-
.. productionlist::
137+
.. productionlist:: python-grammar
138138
parenth_form: "(" [`starred_expression`] ")"
139139

140140
A parenthesized expression list yields whatever that expression list yields: if
@@ -177,7 +177,7 @@ called "displays", each of them in two flavors:
177177

178178
Common syntax elements for comprehensions are:
179179

180-
.. productionlist::
180+
.. productionlist:: python-grammar
181181
comprehension: `assignment_expression` `comp_for`
182182
comp_for: ["async"] "for" `target_list` "in" `or_test` [`comp_iter`]
183183
comp_iter: `comp_for` | `comp_if`
@@ -243,7 +243,7 @@ List displays
243243
A list display is a possibly empty series of expressions enclosed in square
244244
brackets:
245245

246-
.. productionlist::
246+
.. productionlist:: python-grammar
247247
list_display: "[" [`starred_list` | `comprehension`] "]"
248248

249249
A list display yields a new list object, the contents being specified by either
@@ -267,7 +267,7 @@ Set displays
267267
A set display is denoted by curly braces and distinguishable from dictionary
268268
displays by the lack of colons separating keys and values:
269269

270-
.. productionlist::
270+
.. productionlist:: python-grammar
271271
set_display: "{" (`starred_list` | `comprehension`) "}"
272272

273273
A set display yields a new mutable set object, the contents being specified by
@@ -296,7 +296,7 @@ Dictionary displays
296296
A dictionary display is a possibly empty series of key/datum pairs enclosed in
297297
curly braces:
298298

299-
.. productionlist::
299+
.. productionlist:: python-grammar
300300
dict_display: "{" [`key_datum_list` | `dict_comprehension`] "}"
301301
key_datum_list: `key_datum` ("," `key_datum`)* [","]
302302
key_datum: `expression` ":" `expression` | "**" `or_expr`
@@ -355,7 +355,7 @@ Generator expressions
355355

356356
A generator expression is a compact generator notation in parentheses:
357357

358-
.. productionlist::
358+
.. productionlist:: python-grammar
359359
generator_expression: "(" `expression` `comp_for` ")"
360360

361361
A generator expression yields a new generator object. Its syntax is the same as
@@ -409,7 +409,7 @@ Yield expressions
409409
pair: yield; expression
410410
pair: generator; function
411411

412-
.. productionlist::
412+
.. productionlist:: python-grammar
413413
yield_atom: "(" `yield_expression` ")"
414414
yield_expression: "yield" [`expression_list` | "from" `expression`]
415415

@@ -746,7 +746,7 @@ Primaries
746746
Primaries represent the most tightly bound operations of the language. Their
747747
syntax is:
748748

749-
.. productionlist::
749+
.. productionlist:: python-grammar
750750
primary: `atom` | `attributeref` | `subscription` | `slicing` | `call`
751751

752752

@@ -761,7 +761,7 @@ Attribute references
761761

762762
An attribute reference is a primary followed by a period and a name:
763763

764-
.. productionlist::
764+
.. productionlist:: python-grammar
765765
attributeref: `primary` "." `identifier`
766766

767767
.. index::
@@ -799,7 +799,7 @@ Subscriptions
799799
A subscription selects an item of a sequence (string, tuple or list) or mapping
800800
(dictionary) object:
801801

802-
.. productionlist::
802+
.. productionlist:: python-grammar
803803
subscription: `primary` "[" `expression_list` "]"
804804

805805
The primary must evaluate to an object that supports subscription (lists or
@@ -855,7 +855,7 @@ A slicing selects a range of items in a sequence object (e.g., a string, tuple
855855
or list). Slicings may be used as expressions or as targets in assignment or
856856
:keyword:`del` statements. The syntax for a slicing:
857857

858-
.. productionlist::
858+
.. productionlist:: python-grammar
859859
slicing: `primary` "[" `slice_list` "]"
860860
slice_list: `slice_item` ("," `slice_item`)* [","]
861861
slice_item: `expression` | `proper_slice`
@@ -905,7 +905,7 @@ Calls
905905
A call calls a callable object (e.g., a :term:`function`) with a possibly empty
906906
series of :term:`arguments <argument>`:
907907

908-
.. productionlist::
908+
.. productionlist:: python-grammar
909909
call: `primary` "(" [`argument_list` [","] | `comprehension`] ")"
910910
argument_list: `positional_arguments` ["," `starred_and_keywords`]
911911
: ["," `keywords_arguments`]
@@ -1088,7 +1088,7 @@ Await expression
10881088
Suspend the execution of :term:`coroutine` on an :term:`awaitable` object.
10891089
Can only be used inside a :term:`coroutine function`.
10901090

1091-
.. productionlist::
1091+
.. productionlist:: python-grammar
10921092
await_expr: "await" `primary`
10931093

10941094
.. versionadded:: 3.5
@@ -1106,7 +1106,7 @@ The power operator
11061106
The power operator binds more tightly than unary operators on its left; it binds
11071107
less tightly than unary operators on its right. The syntax is:
11081108

1109-
.. productionlist::
1109+
.. productionlist:: python-grammar
11101110
power: (`await_expr` | `primary`) ["**" `u_expr`]
11111111

11121112
Thus, in an unparenthesized sequence of power and unary operators, the operators
@@ -1139,7 +1139,7 @@ Unary arithmetic and bitwise operations
11391139

11401140
All unary arithmetic and bitwise operations have the same priority:
11411141

1142-
.. productionlist::
1142+
.. productionlist:: python-grammar
11431143
u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr`
11441144

11451145
.. index::
@@ -1183,7 +1183,7 @@ that some of these operations also apply to certain non-numeric types. Apart
11831183
from the power operator, there are only two levels, one for multiplicative
11841184
operators and one for additive operators:
11851185

1186-
.. productionlist::
1186+
.. productionlist:: python-grammar
11871187
m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "@" `m_expr` |
11881188
: `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` |
11891189
: `m_expr` "%" `u_expr`
@@ -1279,7 +1279,7 @@ Shifting operations
12791279

12801280
The shifting operations have lower priority than the arithmetic operations:
12811281

1282-
.. productionlist::
1282+
.. productionlist:: python-grammar
12831283
shift_expr: `a_expr` | `shift_expr` ("<<" | ">>") `a_expr`
12841284

12851285
These operators accept integers as arguments. They shift the first argument to
@@ -1300,7 +1300,7 @@ Binary bitwise operations
13001300

13011301
Each of the three bitwise operations has a different priority level:
13021302

1303-
.. productionlist::
1303+
.. productionlist:: python-grammar
13041304
and_expr: `shift_expr` | `and_expr` "&" `shift_expr`
13051305
xor_expr: `and_expr` | `xor_expr` "^" `and_expr`
13061306
or_expr: `xor_expr` | `or_expr` "|" `xor_expr`
@@ -1349,7 +1349,7 @@ lower than that of any arithmetic, shifting or bitwise operation. Also unlike
13491349
C, expressions like ``a < b < c`` have the interpretation that is conventional
13501350
in mathematics:
13511351

1352-
.. productionlist::
1352+
.. productionlist:: python-grammar
13531353
comparison: `or_expr` (`comp_operator` `or_expr`)*
13541354
comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!="
13551355
: | "is" ["not"] | ["not"] "in"
@@ -1608,7 +1608,7 @@ Boolean operations
16081608
pair: Conditional; expression
16091609
pair: Boolean; operation
16101610

1611-
.. productionlist::
1611+
.. productionlist:: python-grammar
16121612
or_test: `and_test` | `or_test` "or" `and_test`
16131613
and_test: `not_test` | `and_test` "and" `not_test`
16141614
not_test: `comparison` | "not" `not_test`
@@ -1647,7 +1647,7 @@ returns a boolean value regardless of the type of its argument
16471647
Assignment expressions
16481648
======================
16491649

1650-
.. productionlist::
1650+
.. productionlist:: python-grammar
16511651
assignment_expression: [`identifier` ":="] `expression`
16521652

16531653
An assignment expression (sometimes also called a "named expression" or
@@ -1683,7 +1683,7 @@ Conditional expressions
16831683
single: if; conditional expression
16841684
single: else; conditional expression
16851685

1686-
.. productionlist::
1686+
.. productionlist:: python-grammar
16871687
conditional_expression: `or_test` ["if" `or_test` "else" `expression`]
16881688
expression: `conditional_expression` | `lambda_expr`
16891689
expression_nocond: `or_test` | `lambda_expr_nocond`
@@ -1710,7 +1710,7 @@ Lambdas
17101710
pair: anonymous; function
17111711
single: : (colon); lambda expression
17121712

1713-
.. productionlist::
1713+
.. productionlist:: python-grammar
17141714
lambda_expr: "lambda" [`parameter_list`] ":" `expression`
17151715
lambda_expr_nocond: "lambda" [`parameter_list`] ":" `expression_nocond`
17161716

@@ -1737,7 +1737,7 @@ Expression lists
17371737
pair: expression; list
17381738
single: , (comma); expression list
17391739

1740-
.. productionlist::
1740+
.. productionlist:: python-grammar
17411741
expression_list: `expression` ("," `expression`)* [","]
17421742
starred_list: `starred_item` ("," `starred_item`)* [","]
17431743
starred_expression: `expression` | (`starred_item` ",")* [`starred_item`]

Doc/reference/introduction.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ Notation
9393
The descriptions of lexical analysis and syntax use a modified BNF grammar
9494
notation. This uses the following style of definition:
9595

96-
.. productionlist::
96+
.. productionlist:: notation
9797
name: `lc_letter` (`lc_letter` | "_")*
9898
lc_letter: "a"..."z"
9999

0 commit comments

Comments
 (0)
0