Docs: Link tokens in the format string grammars (#108184)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 262b785bbcbfc17dde4073b3401d1c1b0f9105a5..1867678b2077fc14151873db7bb1e8453a576f07 100644 (file)
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -208,13 +208,13 @@ The grammar for a replacement field is as follows:
 
 .. productionlist:: format-string
    replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
-   field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
-   arg_name: [`identifier` | `digit`+]
-   attribute_name: `identifier`
-   element_index: `digit`+ | `index_string`
+   field_name: `arg_name` ("." `attribute_name` | "[" `element_index` "]")*
+   arg_name: [`~python-grammar:identifier` | `~python-grammar:digit`+]
+   attribute_name: `~python-grammar:identifier`
+   element_index: `~python-grammar:digit`+ | `index_string`
    index_string: <any source character except "]"> +
    conversion: "r" | "s" | "a"
-   format_spec: <described in the next section>
+   format_spec: `format-spec:format_spec`
 
 In less formal terms, the replacement field can start with a *field_name* that specifies
 the object whose value is to be formatted and inserted
@@ -316,9 +316,9 @@ The general form of a *standard format specifier* is:
    fill: <any character>
    align: "<" | ">" | "=" | "^"
    sign: "+" | "-" | " "
-   width: `digit`+
+   width: `~python-grammar:digit`+
    grouping_option: "_" | ","
-   precision: `digit`+
+   precision: `~python-grammar:digit`+
    type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"
 
 If a valid *align* value is specified, it can be preceded by a *fill*

diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index c4f9b07dc916c942acd68b0b9f62bdbaef420a2f..d80af40bbdca4c6107abf56c3d6de88ec3794011 100644 (file)
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -77,7 +77,6 @@ Doc/library/smtplib.rst
 Doc/library/socket.rst
 Doc/library/ssl.rst
 Doc/library/stdtypes.rst
-Doc/library/string.rst
 Doc/library/subprocess.rst
 Doc/library/termios.rst
 Doc/library/test.rst

diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 31c2544caf601c063572c15c974eaa16d436ca2f..cd441836f62bde4601f81ae6a02d5bfb25dab8b2 100644 (file)
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -48,6 +48,11 @@ Body.enum.converters['loweralpha'] = \
     Body.enum.converters['lowerroman'] = \
     Body.enum.converters['upperroman'] = lambda x: None
 
+# monkey-patch the productionlist directive to allow hyphens in group names
+# https://github.com/sphinx-doc/sphinx/issues/11854
+from sphinx.domains import std
+
+std.token_re = re.compile(r'`((~?[\w-]*:)?\w+)`')
 
 # Support for marking up and linking to bugs.python.org issues