Repository navigation
Minor warning messages when compiling documentation #73707
Description
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 2021-09-12.23:47:59.525>
created_at = <Date 2017-02-10.08:14:19.078>
labels = ['build', '3.7', 'docs']
title = 'Minor warning messages when compiling documentation'
updated_at = <Date 2021-09-12.23:47:59.524>
user = 'https://github.com/JDLH'bugs.python.org fields:
activity = <Date 2021-09-12.23:47:59.524>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-09-12.23:47:59.525>
closer = 'iritkatriel'
components = ['Documentation']
creation = <Date 2017-02-10.08:14:19.078>
creator = 'JDLH'
dependencies = ['29387']
files = []
hgrepos = []
issue_num = 29521
keywords = []
message_count = 19.0
messages = ['287480', '287484', '287498', '287571', '287631', '287632', '287695', '287897', '287898', '287899', '287904', '287922', '288105', '288107', '290431', '290432', '290436', '290437', '291433']
nosy_count = 7.0
nosy_names = ['ncoghlan', 'vstinner', 'brian.curtin', 'docs@python', 'martin.panter', 'Mariatta', 'JDLH']
pr_nums = ['76', '41', '68', '106', '110', '111', '146', '670']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'compile error'
url = 'https://bugs.python.org/issue29521'
versions = ['Python 3.7']
Activity
jdlh commentedon Feb 10, 2017
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
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_preambleandlatex_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 tolatex_paper_size. Those references are rewritten aslatex_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](https://github.com/python/cpython/blob/main/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.
vadmium commentedon Feb 10, 2017
Jim, regarding Doc/faq/windows.rst, this warning lead me to open bpo-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
backticksas quotes (Slightly more palatable than backslashes; this file is meant to be readable as plain text as well.)jdlh commentedon Feb 10, 2017
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 #76 ready for review.
jdlh commentedon Feb 10, 2017
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.
jdlh commentedon Feb 12, 2017
It looks like commit e7ffb99 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 #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.
jdlh commentedon Feb 12, 2017
I submitted a PR #41 to the new Github repo which finishes clearing the warnings in this bug report.
I would appreciate review and committing.
vstinner commentedon Feb 13, 2017
The commit 3d707be broke the Docs buildbot slave. I proposed #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
vstinner commentedon Feb 15, 2017
New changeset de553b8 by Victor Stinner in branch '3.5':
bpo-29521 update Misc/ACKS (#111)
de553b8
vstinner commentedon Feb 15, 2017
New changeset 02e3357 by Victor Stinner in branch '3.6':
bpo-29521 update Misc/ACKS (#110)
02e3357
vstinner commentedon Feb 15, 2017
New changeset 85064db by Victor Stinner in branch 'master':
bpo-29521 update Misc/ACKS (#106)
85064db
vstinner commentedon Feb 15, 2017
New changeset b300c66 by GitHub in branch '3.6':
Backport36 doc fixes: PR#68 and PR#124 (#125)
b300c66
vstinner commentedon Feb 16, 2017
New changeset 5e04dfe by GitHub in branch '3.5':
Backport35 doc fixes: PR#68 and PR#124 (#125) (#126)
5e04dfe
ncoghlan commentedon Feb 19, 2017
New changeset 3337d33 by Nick Coghlan in branch '3.6':
[backport to 3.6] bpo-29529: Add .travis.yml to 3.6 branch (#25)
3337d33
ncoghlan commentedon Feb 19, 2017
New changeset 24bfe15 by Nick Coghlan in branch '3.5':
[backport to 3.5] bpo-29529: Add .travis.yml to 3.5 branch (#26)
24bfe15
Mariatta commentedon Mar 25, 2017
New changeset db3deb9 by Mariatta in branch '3.6':
bpo-29521 Fix two minor documentation build warnings (#41) (#83)
db3deb9
Mariatta commentedon Mar 25, 2017
New changeset 38c8354 by Mariatta in branch '3.5':
bpo-29521 Fix two minor documentation build warnings (#41) (#84)
38c8354
vstinner commentedon Mar 25, 2017
New changeset 2b50186 by Victor Stinner in branch 'master':
Travis CI: run rstlint.py in the docs job (#68)
2b50186
briancurtin commentedon Mar 25, 2017
New changeset 3d707be by Brian Curtin (Jim DeLaHunt) in branch 'master':
bpo-29521 Fix two minor documentation build warnings (#41)
3d707be
Mariatta commentedon Apr 10, 2017
New changeset e0cba5b by Mariatta in branch '2.7':
[2.7] bpo-29521: Fix two minor documentation build warnings (GH-41) (GH-670)
e0cba5b