Docs build fails in 3.12

[Yhg1s]

Bug report

Bug description:

Building the epub version of the docs fails in 3.12:

% cd Docs
% make venv
[...]
% make epub
mkdir -p build
Building NEWS from Misc/NEWS.d with blurb
PATH=./venv/bin:$PATH sphinx-build -b epub -d build/doctrees -j auto   -W . build/epub
Running Sphinx v8.1.3
matplotlib is not installed, social cards will not be generated
loading translations [en]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [epub]: targets for 501 source files that are out of date
[....]
checking consistency... /home/thomas/python/python/3.12/Doc/howto/argparse.rst: document is referenced in multiple toctrees: ['library/argparse', 'howto/index'], selecting: library/argparse <- howto/argparse
done
[...]
writing toc.ncx file...
WARNING: duplicated ToC entry found: howto/argparse.xhtml [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#concepts [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#the-basics [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#introducing-positional-arguments [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#introducing-optional-arguments [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#short-options [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#combining-positional-and-optional-arguments [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#getting-a-little-more-advanced [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#specifying-ambiguous-arguments [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#conflicting-options [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#how-to-translate-the-argparse-output [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#custom-type-converters [epub.duplicated_toc_entry]
WARNING: duplicated ToC entry found: howto/argparse.xhtml#conclusion [epub.duplicated_toc_entry]
Writing evaluated template result to /home/thomas/python/python/3.12/Doc/build/epub/toc.ncx
writing Python.epub file...
build finished with problems, 13 warnings (with warnings treated as errors).
make: *** [Makefile:56: build] Error 1

Epubs are built as part of make dist (in the Doc tree), which is part of the release process. I'm not sure if the warning during "checking consistency" about howto/arparse and library/argparse is relevant. The Python 3.13 version builds successfully without warnings about duplicate ToC entries, but it does produce the warning about howto/argparse and library/argparse.

CPython versions tested on:

3.12, 3.13

Operating systems tested on:

Linux

[Yhg1s]

FWIW: I built the 3.12.8 release's docs by disabling warnings and making no other changes. If this issue is fixed by something other than working around the warnings (i.e. they represent an actual problem that we should've avoided instead), we may want to re-upload the docs (possibly just the epub?) for 3.12.8.

The cause of the warnings seems to be that multiple toctrees(https://github.com/python/cpython/blob/3.12/Doc/library/argparse.rst?plain=1#L2111, and https://github.com/python/cpython/blob/3.12/Doc/howto/index.rst?plain=1#L29) contain howto/argparse.rst and none of which have :hidden: option. In the latest version, this option was added by gh-119366, so backporting this PR resolves this issue.

[hugovk]

@koyuki7w Thanks for finding that.

I've opened the backport and confirmed it fixes the epub failure: #127811.

[hugovk]

And merged :)