classification
Title: inconsistencies in docs builds (Sphinx 2)
Type: compile error Stage: patch review
Components: Documentation Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Anthony Sottile, SilentGhost, docs@python, drj, jaraco, mbussonn, mdk, xtreak
Priority: normal Keywords: patch

Created on 2019-05-08 16:03 by jaraco, last changed 2019-09-02 19:17 by jaraco.

Pull Requests
URL Status Linked Edit
PR 13579 merged Anthony Sottile, 2019-06-09 19:14
PR 15649 merged miss-islington, 2019-09-02 16:01
PR 15653 merged Anthony Sottile, 2019-09-02 17:31
Messages (9)
msg341897 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2019-05-08 16:03
In working on some docs contributions, I've run into issues where docs builds are failing in CI differently than they're failing locally.

Locally, running `make venv` from `Docs/` results in Sphinx 2, whereas on Azure Pipelines, the docs are built with Sphinx 1.8.2 (https://github.com/python/cpython/blob/1d4b16051f8550fd7dada3670a3e83ae13b99d3b/.azure-pipelines/docs-steps.yml#L15).

When running with Sphinx 2, this error emerges when running `make suspicious` when a change is around that triggers suspicious code (such as this commit https://github.com/python/cpython/pull/12547/commits/9bde7faf6f051d4a7306ac8629d915ce069392f7):

Exception occurred:
  File "/Users/jaraco/code/public/cpython/Doc/tools/extensions/suspicious.py", line 154, in report_issue
    self.warn('[%s:%d] "%s" found in "%-.120s"' %
AttributeError: 'CheckSuspiciousMarkupBuilder' object has no attribute 'warn'

First, we probably want to make these processes consistent (define the dependencies in exactly one place).

Second, we should probably determine why the doc builds are failing on Sphinx 2 and update the `suspicious` code to support Sphinx 2.
msg341995 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2019-05-09 19:49
Hi Jaraco,

We're using sphinx 1.8 in production (docs.python.org) but we're ready for sphinx 2 so we should upgrade, and when we'll upgrade, we'll upgrade it everywhere.

You're right, `make venv` does not specify a version, at the sphinx 2 bump we'll have to pin it here too and try to get a single point of truth about which version we're using.

I've just locally ran sphinx 2.0.0 on 071cbd4ea1 (the current tip of your PR) and I'm not getting any error, which one are you getting?
msg341997 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2019-05-09 20:26
> Second, we should probably determine why the doc builds are failing on Sphinx 2 and update the `suspicious` code to support Sphinx 2.

They're failing because in sphinx 2 old and deprecated (since 1.6) custom logging API was removed. So all Builder.warn calls will have to be changed to use logging module (this applies to other similar methods, luckily they had the same names as logging methods).
msg343574 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2019-05-26 17:57
See also https://github.com/python/cpython/pull/13579 that replaces self.warn with self.logger.warn in Doc/tools/extensions/suspicious.py
msg343578 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2019-05-26 19:11
> I've just locally ran sphinx 2.0.0 on 071cbd4ea1 (the current tip of your PR) and I'm not getting any error, which one are you getting?

The issue occurs on 2347d3ae36 with `make suspicious` with Sphinx 2.0.0 and 2.0.1.

```
Doc 2347d3ae36 $ make suspicious                                                                                                                                               
mkdir -p build
Building NEWS from Misc/NEWS.d with blurb
PATH=./venv/bin:$PATH sphinx-build -b suspicious -d build/doctrees -D latex_elements.papersize=  -W . build/suspicious 
Running Sphinx v2.0.1
loading ignore rules... done, 352 rules loaded
building [mo]: targets for 0 po files that are out of date
building [suspicious]: targets for 476 source files that are out of date
updating environment: 476 added, 0 changed, 0 removed
/Users/jaraco/code/public/cpython/Doc/tools/extensions/pyspecific.py:274: RemovedInSphinx30Warning: env.note_versionchange() is deprecated. Please use ChangeSetDomain.note_changeset() instead.
  env.note_versionchange('deprecated', version[0], node, self.lineno)
reading sources... [100%] whatsnew/index                                                                                                                                       
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 53%] library/importlib.metadata                                                                                                                            
Exception occurred:
  File "/Users/jaraco/code/public/cpython/Doc/tools/extensions/suspicious.py", line 154, in report_issue
    self.warn('[%s:%d] "%s" found in "%-.120s"' %
AttributeError: 'CheckSuspiciousMarkupBuilder' object has no attribute 'warn'
The full traceback has been saved in /var/folders/c6/v7hnmq453xb6p2dbz1gqc6rr0000gn/T/sphinx-err-g3i65y10.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make[1]: *** [build] Error 2
make: *** [suspicious] Error 1
Suspicious check complete; look for any errors in the above output or in build/suspicious/suspicious.csv.  If all issues are false positives, append that file to tools/susp-ignored.csv.
```
msg345221 - (view) Author: David Jones (drj) * Date: 2019-06-11 11:11
I believe the issue is only triggered if you actually have some suspicious markup in your documentation (which is why your plain build on Sphinx 2 appears to work).

Remove some lines from Doc/tools/susp-ignored.csv to trigger it.
msg351016 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2019-09-02 16:01
New changeset e1786b54162e2bfb01ca5aafa19d596c4af5a803 by Jason R. Coombs (Anthony Sottile) in branch 'master':
bpo-36853: Fix suspicious.py to actually print the unused rules (#13579)
https://github.com/python/cpython/commit/e1786b54162e2bfb01ca5aafa19d596c4af5a803
msg351019 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2019-09-02 16:12
New changeset b365cfae4675ae90df329cb1179a5664e8283c13 by Jason R. Coombs (Miss Islington (bot)) in branch '3.8':
bpo-36853: Fix suspicious.py to actually print the unused rules (GH-13579) (GH-15649)
https://github.com/python/cpython/commit/b365cfae4675ae90df329cb1179a5664e8283c13
msg351036 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2019-09-02 19:17
New changeset ebe709dc1d7c1f9f07dc7d77e53674d2500b223e by Jason R. Coombs (Anthony Sottile) in branch '3.7':
bpo-36853: Fix suspicious.py to actually print the unused rules (#13579) (#15653)
https://github.com/python/cpython/commit/ebe709dc1d7c1f9f07dc7d77e53674d2500b223e
History
Date User Action Args
2019-09-02 19:17:28jaracosetmessages: + msg351036
2019-09-02 17:31:50Anthony Sottilesetpull_requests: + pull_request15320
2019-09-02 16:12:22jaracosetmessages: + msg351019
2019-09-02 16:01:36miss-islingtonsetpull_requests: + pull_request15316
2019-09-02 16:01:27jaracosetmessages: + msg351016
2019-06-11 11:11:38drjsetnosy: + drj
messages: + msg345221
2019-06-09 19:20:49Anthony Sottilesetnosy: + Anthony Sottile
2019-06-09 19:14:00Anthony Sottilesetkeywords: + patch
stage: patch review
pull_requests: + pull_request13799
2019-05-26 19:11:52jaracosetmessages: + msg343578
2019-05-26 17:57:11xtreaksetnosy: + xtreak
messages: + msg343574
2019-05-26 17:50:11SilentGhostlinkissue37057 superseder
2019-05-26 17:38:37mbussonnsetnosy: + mbussonn
2019-05-09 20:26:05SilentGhostsetnosy: + SilentGhost
messages: + msg341997
2019-05-09 19:49:55mdksetmessages: + msg341995
2019-05-09 18:45:30ned.deilysetnosy: + mdk
2019-05-08 16:03:28jaracocreate