Documentation job fails on CIs: duplicate token description of format_spec

[vstinner]

BPO	41762
Nosy	@terryjreedy, @vstinner, @cameron-simpson, @ambv, @corona10, @pablogsal, @miss-islington, @isidentical
PRs	[WIP] DEBUG bpo-41762 (Sphinx warnings) #22199 bpo-41762: Fix usage of productionlist markup in the doc #22281 [3.8] bpo-41762: Fix usage of productionlist markup in the doc (GH-22281) #22300 [3.9] bpo-41762: Fix usage of productionlist markup in the doc (GH-22281) #22301

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-09-18.08:32:20.436>
created_at = <Date 2020-09-11.10:45:24.312>
labels = ['3.8', '3.9', '3.10', 'docs']
title = 'Documentation job fails on CIs: duplicate token description of format_spec'
updated_at = <Date 2020-10-05.16:10:20.348>
user = 'https://github.com/vstinner'

bugs.python.org fields:

activity = <Date 2020-10-05.16:10:20.348>
actor = 'lukasz.langa'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-09-18.08:32:20.436>
closer = 'vstinner'
components = ['Documentation']
creation = <Date 2020-09-11.10:45:24.312>
creator = 'vstinner'
dependencies = []
files = []
hgrepos = []
issue_num = 41762
keywords = ['patch']
message_count = 14.0
messages = ['376717', '376718', '376722', '376726', '376765', '376774', '376787', '376788', '376999', '377089', '377091', '377095', '377096', '378058']
nosy_count = 9.0
nosy_names = ['terry.reedy', 'vstinner', 'cameron', 'docs@python', 'lukasz.langa', 'corona10', 'pablogsal', 'miss-islington', 'BTaskaya']
pr_nums = ['22199', '22281', '22300', '22301']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue41762'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[vstinner]

https://travis-ci.com/github/python/cpython/jobs/383579366

Warning, treated as error:

/home/travis/build/python/cpython/Doc/library/string.rst:311:duplicate token description of format_spec, other instance in reference/lexical_analysis

[vstinner]

There are two format_spec definitions:

"format_spec ::= [[fill]align][sign][#][0][width][grouping_option][.precision][type]"
https://docs.python.org/dev/library/string.html#format-specification-mini-language

"format_spec ::= (literal_char | NULL | replacement_field)*"
https://docs.python.org/dev/reference/lexical_analysis.html#formatted-string-literals

[vstinner]

I failed to reproduce the issue locally. I tried:

cd Doc
make clean
make venv PYTHON=../python
./venv/bin/python -m pip install sphinx==2.2.0 blurb python-docs-theme
make check suspicious html SPHINXOPTS="-q -W -j4"

[vstinner]

Oh. It seems like the warning only occurs randomly!? It is gone on one of my PR.

[corona10]

>>> sphinx.__version__
'3.2.1

I can reproduce this issue consistantly on my local machine with this environment.

[terryjreedy]

Two issues about Sphinx 3.2.1 failing with "duplicate token description"
(posted on both)
bpo-41760 'sign', multiple people nosy, failed where?
bpo-41762 'format_spec', on Travis, PR by Victor Stinner (2.2.0 okay)

[vstinner]

I closed bpo-41760 as a duplicate of this issue.

[vstinner]

I closed bpo-41760 as a duplicate of this issue.

The error message was different but similar:

Warning, treated as error:
/<<PKGBUILDDIR>>/Doc/library/string.rst:311:duplicate token description of sign, other instance in library/functions

[vstinner]

".. productionlist::" markup is related to "Grammar production displays":
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#grammar-production-displays

We can try to pass a different unique name to each ".. productionlist::" markup:

"The productionGroup argument to productionlist serves to distinguish different sets of production lists that belong to different grammars. Multiple production lists with the same productionGroup thus define rules in the same scope."