Travis: doc job is broken

[vstinner]

BPO	29527
Nosy	@brettcannon, @vstinner, @zware, @refi64
PRs	Make Travis docs build more lenient #16 bpo-29527: Disable broken Travis docs job #7

^{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 2017-02-12.21:55:17.682>
created_at = <Date 2017-02-10.23:49:33.905>
labels = ['3.7', 'tests']
title = 'Travis: doc job is broken'
updated_at = <Date 2017-03-25.00:56:35.754>
user = 'https://github.com/vstinner'

bugs.python.org fields:

activity = <Date 2017-03-25.00:56:35.754>
actor = 'vstinner'
assignee = 'none'
closed = True
closed_date = <Date 2017-02-12.21:55:17.682>
closer = 'vstinner'
components = ['Tests']
creation = <Date 2017-02-10.23:49:33.905>
creator = 'vstinner'
dependencies = []
files = []
hgrepos = []
issue_num = 29527
keywords = []
message_count = 8.0
messages = ['287573', '287574', '287579', '287586', '287617', '287629', '287655', '290456']
nosy_count = 4.0
nosy_names = ['brett.cannon', 'vstinner', 'zach.ware', 'refi64']
pr_nums = ['16', '7']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue29527'
versions = ['Python 3.7']

[vstinner]

I suggest to disable the job until it's fixed, just to fix Travis right now. This issue will track the bug to find a solution.

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

$ make html SPHINXBUILD="./venv/bin/python3 -m sphinx" SPHINXOPTS="-nW -q -b linkcheck"
./venv/bin/python3 -m sphinx -b html -d build/doctrees -D latex_paper_size= -nW -q -b linkcheck . build/html 

Warning, treated as error:
WARNING: latex_preamble is deprecated. Use latex_elements['preamble'] instead.

make: *** [build] Error 1

[brettcannon]

What would it take to simply fix the docs?

And we shouldn't disable the check entirely if fixing it is difficult, but instead just let warnings be warnings until we fix all warnings and then make them be errors again.

[vstinner]

And we shouldn't disable the check entirely if fixing it is difficult, but instead just let warnings be warnings until we fix all warnings and then make them be errors again.

Ok, I changed my change (I got the same proposal in the PR). So I removed -W option:
0d5f110

[refi64]

Trying to fix this in https://github.com/python/cpython/pull/9...but...

Currently there are approx *pause for effect* 6,245 warnings!

Out of those, around 6,243 are 'reference target not found' warnings, spanning over 290 files:

/media/ryan/stuff/cpython/Doc/whatsnew/3.7.rst:121: WARNING: c:member reference target not found: doc
/media/ryan/stuff/cpython/Doc/whatsnew/3.7.rst:121: WARNING: c:type reference target not found: PyGetSetDef
/media/ryan/stuff/cpython/Doc/whatsnew/3.7.rst:121: WARNING: c:type reference target not found: wrapperbase
/media/ryan/stuff/cpython/Doc/whatsnew/3.7.rst:157: WARNING: py:mod reference target not found: ntpath
../../Misc/NEWS:348: WARNING: py:data reference target not found: socket.TCP_CONGESTION
../../Misc/NEWS:348: WARNING: py:data reference target not found: socket.TCP_USER_TIMEOUT
../../Misc/NEWS:1005: WARNING: py:data reference target not found: socket.TCP_CONGESTION
../../Misc/NEWS:1005: WARNING: py:data reference target not found: socket.TCP_USER_TIMEOUT
../../Misc/NEWS:2718: WARNING: py:obj reference target not found: idlelib/.py
../../Misc/NEWS:2718: WARNING: py:obj reference target not found: idle_test/test_.py
../../Misc/NEWS:2837: WARNING: c:func reference target not found: malloc
../../Misc/NEWS:2883: WARNING: c:func reference target not found: PyObject_Malloc

For some reason, I don't feel like fixing 6,200 warnings is really feasible (or at least for me), so would it be worth it to, in the mean time, disable this specific kind of warning, at least for the CI builds?

[brettcannon]

It really depends on why the warnings are there. If it's a configuration issue with how Misc/NEWS is being built then that can be fixed to deal with a lot of warnings upfront. Otherwise we can also strip out the references from Misc/NEWS to deal with the warnings.

[zware]

PR16 made the Travis build situation better, but we still have some warnings to look into. I thought we had a PR for that, but I can't seem to find it.

[vstinner]

I see that Travis CI now compiles the doc to HTML, there is a single warning and the doc works. So I close the issue. Thanks!

If you want to upgrade Sphinx, fix more warnings, etc. : please open new more specific issues for these tasks.

[vstinner]

New changeset 0d5f110 by Victor Stinner in branch 'master':
Don't treat warnings as error in Travis docs job (#7)
0d5f110