Travis CI: Documentation tests fails with Sphinx 2.1

[vstinner]

BPO	37136
Nosy	@gvanrossum, @warsaw, @vstinner, @ned-deily, @bitdancer, @njsmith, @maxking, @JulienPalard
PRs	WIP: debug bpo-37136 #13764

^{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 2019-06-13.04:07:11.675>
created_at = <Date 2019-06-03.01:09:22.881>
labels = ['build', '3.8']
title = 'Travis CI: Documentation tests fails with Sphinx 2.1'
updated_at = <Date 2019-06-13.04:07:11.671>
user = 'https://github.com/vstinner'

bugs.python.org fields:

activity = <Date 2019-06-13.04:07:11.671>
actor = 'ned.deily'
assignee = 'none'
closed = True
closed_date = <Date 2019-06-13.04:07:11.675>
closer = 'ned.deily'
components = ['Build']
creation = <Date 2019-06-03.01:09:22.881>
creator = 'vstinner'
dependencies = []
files = []
hgrepos = []
issue_num = 37136
keywords = ['patch']
message_count = 6.0
messages = ['344352', '344361', '344362', '344363', '345444', '345455']
nosy_count = 8.0
nosy_names = ['gvanrossum', 'barry', 'vstinner', 'ned.deily', 'r.david.murray', 'njs', 'maxking', 'mdk']
pr_nums = ['13764']
priority = None
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue37136'
versions = ['Python 3.8']

[vstinner]

Travis CI: "Documentation tests" failed with:

Successfully installed Jinja2-2.10.1 MarkupSafe-1.1.1 Pygments-2.4.2 Sphinx-2.1.0 alabaster-0.7.12 babel-2.7.0 blurb-1.0.7 certifi-2019.3.9 chardet-3.0.4 docutils-0.14 idna-2.8 imagesize-1.1.0 packaging-19.0 pyparsing-2.4.0 python-docs-theme-2018.7 pytz-2019.1 requests-2.22.0 six-1.12.0 snowballstemmer-1.2.1 sphinxcontrib-applehelp-1.0.1 sphinxcontrib-devhelp-1.0.1 sphinxcontrib-htmlhelp-1.0.2 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.2 sphinxcontrib-serializinghtml-1.1.3 urllib3-1.25.3
(...)
Warning, treated as error:
duplicate object description of email.message, other instance in library/email.message, use :noindex: for one of them

https://travis-ci.org/python/cpython/jobs/540532864

ref: #13762

--

Sphinx 2.1 was released yesterday:

https://www.sphinx-doc.org/en/master/changes.html#release-2-1-0-released-jun-02-2019

[vstinner]

I tried but I failed to reproduce the issue using:

git clean -fdx
./configure CFLAGS="-O0"
make

cd Doc
make venv PYTHON=../python

# Successfully installed Jinja2-2.10.1 MarkupSafe-1.1.1 Pygments-2.4.2 Sphinx-2.1.0 alabaster-0.7.12 babel-2.7.0 blurb-1.0.7 certifi-2019.3.9 chardet-3.0.4 docutils-0.14 idna-2.8 imagesize-1.1.0 packaging-19.0 pyparsing-2.4.0 python-docs-theme-2018.7 pytz-2019.1 requests-2.22.0 six-1.12.0 snowballstemmer-1.2.1 sphinxcontrib-applehelp-1.0.1 sphinxcontrib-devhelp-1.0.1 sphinxcontrib-htmlhelp-1.0.2 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.2 sphinxcontrib-serializinghtml-1.1.3 urllib3-1.25.3

# I added "LANG=" to ignore my French locale
# LANG= PATH=./venv/bin:$PATH sphinx-build -b doctest -d build/doctrees -D latex_elements.papersize= -q -W -j4 -W . build/doctest

LANG= make PYTHON=../python SPHINXOPTS="-q -W -j4" doctest

[vstinner]

Tests passed on my PR 13764, so I remove the release blocker status.

It might be something wrong specific to my PR 13762.

[vstinner]

Ok, it's very strange. The test passed when run again manually on Travis CI. I close the issue....

[njsmith]

One of Guido's mentees (I don't know her bpo account name) also ran into this:

https://python.zulipchat.com/#narrow/stream/116742-core.2Fhelp/topic/Weird.20sphinx.20error

Some analysis shows that we do have a bug in the docs – the sphinx '.. module::' directive is only supposed to be used once per module, because it means "this is the canonical documentation for this module, that should be linked to whenever anyone mentions this module".

But we have two documents that use '.. module:: email.message':
Doc/library/email.message.rst
Doc/library/email.compat32-message.rst

I don't know enough about the email module to know what the right fix is, so I'll CC the email-interest-area folks too... maybe email.compat32-message.rst should be using '.. currentmodule:: email.message' instead of '.. module::'?

It's not clear why this error is appearing and disappearing for different people. The sphinx 2.1 release did make some changes in this area:

sphinx-doc/sphinx@259be87

but that doesn't explain why it appears and disappears randomly.

Probably not worth tracking down though, given that we can just fix the underlying problem.

[ned-deily]

The problem with the duplicate .. module:: email.message was fixed about 10 days ago with PR 13742 and backports; the fix adds a :noindex: to the duplicate entry. I'm guessing that people seeing this problem had upgraded to Sphinx 2.1 but had not recently done a rebase of their feature branch to pick up that fix.