classification
Title: Minor warning messages when compiling documentation
Type: compile error Stage:
Components: Documentation Versions: Python 3.7
process
Status: open Resolution:
Dependencies: 29387 Superseder:
Assigned To: docs@python Nosy List: JDLH, docs@python, haypo, martin.panter, ncoghlan
Priority: normal Keywords:

Created on 2017-02-10 08:14 by JDLH, last changed 2017-03-15 05:04 by Mariatta.

Pull Requests
URL Status Linked Edit
PR 76 JDLH, 2017-02-10 09:42
PR 41 JDLH, 2017-02-12 06:41
PR 68 haypo, 2017-02-13 14:19
PR 106 merged Mariatta, 2017-02-15 03:58
PR 110 merged Mariatta, 2017-02-15 04:48
PR 111 merged Mariatta, 2017-02-15 04:48
PR 146 open aktech, 2017-02-18 06:40
PR 670 open Mariatta, 2017-03-15 05:04
Messages (14)
msg287480 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-10 08:14
When I build the documentation on the current CPython code, there are various error and warning messages on the console. 

Here's what my build output looks like. I've marked the messages I'm concerned about with a numbered >>0>> prefix.

===== (beginning of output)
% make html
sphinx-build -b html -d build/doctrees -D latex_paper_size=  . build/html 
Running Sphinx v1.5.2
loading pickled environment... done
>>1>> WARNING: latex_preamble is deprecated. Use latex_elements['preamble'] instead.
>>2>> WARNING: latex_paper_size is deprecated. Use latex_elements['papersize'] instead.
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 466 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] whatsnew/changelog                                                                
>>3>> ../../Misc/NEWS:659: WARNING: Inline emphasis start-string without end-string.
>>4>> ../../Misc/NEWS:659: WARNING: Inline emphasis start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] whatsnew/index                                                                     
>>5>> /Users/jdlh/workspace/cpython_github/Doc/faq/windows.rst:303: WARNING: unknown option: -t
generating indices... genindex py-modindex
writing additional pages... download index
>>6>> WARNING: Now base template defindex.html is deprecated.
 search opensearch
copying images... [100%] using/win_installer.png                                                            
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 6 warnings.

Build finished. The HTML pages are in build/html.
===== (end of output)

This is observed when building documentation from branch master, commit b1dc6b6d5fa20f63f9651df2e7986a066c88ff7d . 
The build command is "cd Doc; make html".

Warning >>6>> is the subject of http://bugs.python.org/issue29520 . It's harder to fix, and I won't address it here.

The other five warnings are pretty easy to fix.

Warnings >>1>>, >>2>> are Sphinx warnings about names used in Doc/conf.py , namely `latex_preamble` and `latex_paper_size`. There are straightforward changes to build a dict latex_elements{}, with keys 'preamble' and 'papersize'. It turns out that makefiles Doc/Makefile and Doc/make.bat also referred to `latex_paper_size`. Those references are rewritten as `latex_elements.papersize`, per Sphinx syntax for external names.

Warnings >>3>>, >>4>> are Sphinx warnings about the text, in Misc/NEWS:661, 
  ```is now of type "const char *" rather of "char *".```
Put a backslash in front of the '*', and the warning disappears.
 
Warning >>5>> is a Sphinx warning about this text, in 
Doc/faq/windows.rst:303:

If you suspect mixed tabs and spaces are causing problems in leading whitespace, run Python with the :option:`-t` switch or run ``Tools/Scripts/tabnanny.py`` to check a directory tree in batch mode.

The notation :option:`-t` seems to need a corresponding ``.. cmdoption:: -t `` entry, perhaps in the same file. There is no such entry.

It turns out that the -t option has no function in Python 3.6, maybe in all of 3.x. Python swallows the option but does nothing. Thus, instead of trying to make the reference to '-t' work, I decided to cut the whole phrase. This paragraph now reads, 

If you suspect mixed tabs and spaces are causing problems in leading whitespace, run ``Tools/Scripts/tabnanny.py`` to check a directory tree in batch mode.

I am making a Pull Request with these fixes. I will shortly link to it from here.
msg287484 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-02-10 08:48
Jim, regarding Doc/faq/windows.rst, this warning lead me to open Issue 29387. We already have discussed a patch for that, and I think it is ready to commit (when it gets to the top of my list, if nobody else beats me to it).

Regarding Misc/NEWS, I think I was going to use ``backticks`` as quotes (Slightly more palatable than backslashes; this file is meant to be readable as plain text as well.)
msg287498 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-10 09:42
Thanks, Martin, for your suggestions.

In Misc/NEWS, I've respelled the ``char *`` as you suggested. 
In faq/windows.rst, I've used your wording from the discussion in http://bugs.python.org/issue29387 .

Pull Request 76 https://github.com/python/cpython/pull/76 ready for review.
msg287571 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-10 21:27
My Pull Request was closed, because apparently  https://github.com/python/cpython/ will not be the new GitHub repo for Python. The actual repo will open on 11. Feb, I'm told. I will repeat the PR there. Please stand by.
msg287631 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-12 05:58
It looks like commit e7ffb99f842ebff97cffa0fc90b18be4e5abecf2 to the new GitHub python/cpython repo, by Ryan Gonzalez, fixed the problems in Doc/conf.py, Doc/Makefile, and Misc/NEWS . It did not fix the problems in Doc/make.bat or Doc/faq/windows.rst .  I'll make a new Pull Request on the new repo to fix these two parts.

That commit was related to https://github.com/python/cpython/pull/9. 

http://bugs.python.org/issue29527 talks about over 6000 warnings in the doc build, maybe including some of these. Another PR appeared to have fixed many of the warnings.
msg287632 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-12 06:41
I submitted a PR https://github.com/python/cpython/pull/41 to the new Github repo which finishes clearing the warnings in this bug report.

I would appreciate review and committing.
msg287695 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2017-02-13 14:19
The commit 3d707be950b387552585451071928e7b39cdfa53 broke the Docs buildbot slave. I proposed https://github.com/python/cpython/pull/68 to run the rstlint.py check on Travis as well, and to fix the 2 warnings.

http://buildbot.python.org/all/builders/Docs%203.x/builds/399/steps/lint/logs/stdio


python3 tools/rstlint.py -i tools -i venv
[1] faq/windows.rst:303: trailing whitespace
[1] faq/windows.rst:305: trailing whitespace
2 problems with severity 1 found.
Makefile:156: recipe for target 'check' failed
msg287897 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2017-02-15 23:14
New changeset de553b8210882823d3df3f1ef6882eba3f8accf3 by Victor Stinner in branch '3.5':
bpo-29521 update Misc/ACKS (#111)
https://github.com/python/cpython/commit/de553b8210882823d3df3f1ef6882eba3f8accf3
msg287898 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2017-02-15 23:14
New changeset 02e3357e089f37c23d0f3d1ebee9aa3d7a1492a9 by Victor Stinner in branch '3.6':
bpo-29521 update Misc/ACKS (#110)
https://github.com/python/cpython/commit/02e3357e089f37c23d0f3d1ebee9aa3d7a1492a9
msg287899 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2017-02-15 23:16
New changeset 85064db281545d587992df61154e76439138319f by Victor Stinner in branch 'master':
bpo-29521 update Misc/ACKS (#106)
https://github.com/python/cpython/commit/85064db281545d587992df61154e76439138319f
msg287904 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2017-02-15 23:56
New changeset b300c660d34d2027d443098ea605a8e0eb51d383 by GitHub in branch '3.6':
Backport36 doc fixes: PR#68 and PR#124 (#125)
https://github.com/python/cpython/commit/b300c660d34d2027d443098ea605a8e0eb51d383
msg287922 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2017-02-16 09:43
New changeset 5e04dfecec478db13031fa507d6b2e21adbce035 by GitHub in branch '3.5':
Backport35 doc fixes: PR#68 and PR#124 (#125) (#126)
https://github.com/python/cpython/commit/5e04dfecec478db13031fa507d6b2e21adbce035
msg288105 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-02-19 05:12
New changeset 3337d33a4518f7ab8a7ab6c9a75b8b92ba348b27 by Nick Coghlan in branch '3.6':
[backport to 3.6] bpo-29529: Add .travis.yml to 3.6 branch (#25)
https://github.com/python/cpython/commit/3337d33a4518f7ab8a7ab6c9a75b8b92ba348b27
msg288107 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-02-19 05:13
New changeset 24bfe15e83c24bf2c2e2654050da809553789002 by Nick Coghlan in branch '3.5':
[backport to 3.5] bpo-29529: Add .travis.yml to 3.5 branch (#26)
https://github.com/python/cpython/commit/24bfe15e83c24bf2c2e2654050da809553789002
History
Date User Action Args
2017-03-15 05:04:03Mariattasetpull_requests: + pull_request553
2017-02-19 05:13:04ncoghlansetmessages: + msg288107
2017-02-19 05:12:02ncoghlansetmessages: + msg288105
2017-02-18 06:40:59aktechsetpull_requests: + pull_request106
2017-02-18 05:26:53ezio.melottisetmessages: - msg288062
2017-02-18 05:13:18ncoghlansetnosy: + ncoghlan
messages: + msg288062
2017-02-16 09:43:18hayposetmessages: + msg287922
2017-02-15 23:56:56hayposetmessages: + msg287904
2017-02-15 23:16:26hayposetmessages: + msg287899
2017-02-15 23:14:44hayposetmessages: + msg287898
2017-02-15 23:14:41hayposetmessages: + msg287897
2017-02-15 04:48:39Mariattasetpull_requests: + pull_request74
2017-02-15 04:48:10Mariattasetpull_requests: + pull_request73
2017-02-15 03:58:55Mariattasetpull_requests: + pull_request69
2017-02-13 14:19:10hayposetnosy: + haypo

messages: + msg287695
pull_requests: + pull_request52
2017-02-12 06:41:25JDLHsetmessages: + msg287632
pull_requests: + pull_request43
2017-02-12 05:58:54JDLHsetmessages: + msg287631
2017-02-10 21:27:40JDLHsetmessages: + msg287571
2017-02-10 09:42:54JDLHsetmessages: + msg287498
pull_requests: + pull_request27
2017-02-10 08:50:10martin.pantersetdependencies: + Tabs vs spaces FAQ out of date
2017-02-10 08:48:09martin.pantersetnosy: + martin.panter
messages: + msg287484
2017-02-10 08:14:19JDLHcreate