[issue29521] Minor warning messages when compiling documentation
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
New submission from Jim DeLaHunt: 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 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. ---------- assignee: docs@python components: Documentation messages: 287480 nosy: JDLH, docs@python priority: normal severity: normal status: open title: Minor warning messages when compiling documentation type: compile error versions: Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Martin Panter added the comment: 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.) ---------- nosy: +martin.panter _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- dependencies: +Tabs vs spaces FAQ out of date _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Jim DeLaHunt added the comment: 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. ---------- pull_requests: +27 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Jim DeLaHunt added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Jim DeLaHunt added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Jim DeLaHunt added the comment: 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. ---------- pull_requests: +43 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
STINNER Victor added the comment: 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/log... 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 ---------- nosy: +haypo pull_requests: +52 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Changes by Mariatta Wijaya <mariatta.wijaya@gmail.com>: ---------- pull_requests: +69 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Changes by Mariatta Wijaya <mariatta.wijaya@gmail.com>: ---------- pull_requests: +73 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Changes by Mariatta Wijaya <mariatta.wijaya@gmail.com>: ---------- pull_requests: +74 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
STINNER Victor added the comment: New changeset de553b8210882823d3df3f1ef6882eba3f8accf3 by Victor Stinner in branch '3.5': bpo-29521 update Misc/ACKS (#111) https://github.com/python/cpython/commit/de553b8210882823d3df3f1ef6882eba3f8... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
STINNER Victor added the comment: New changeset 02e3357e089f37c23d0f3d1ebee9aa3d7a1492a9 by Victor Stinner in branch '3.6': bpo-29521 update Misc/ACKS (#110) https://github.com/python/cpython/commit/02e3357e089f37c23d0f3d1ebee9aa3d7a1... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
STINNER Victor added the comment: New changeset 85064db281545d587992df61154e76439138319f by Victor Stinner in branch 'master': bpo-29521 update Misc/ACKS (#106) https://github.com/python/cpython/commit/85064db281545d587992df61154e7643913... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
STINNER Victor added the comment: New changeset b300c660d34d2027d443098ea605a8e0eb51d383 by GitHub in branch '3.6': Backport36 doc fixes: PR#68 and PR#124 (#125) https://github.com/python/cpython/commit/b300c660d34d2027d443098ea605a8e0eb5... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
STINNER Victor added the comment: 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/5e04dfecec478db13031fa507d6b2e21adb... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Nick Coghlan added the comment: New changeset 85064db281545d587992df61154e76439138319f by Victor Stinner in branch 'ncoghlan-devguide-link': bpo-29521 update Misc/ACKS (#106) https://github.com/python/cpython/commit/85064db281545d587992df61154e7643913... ---------- nosy: +ncoghlan _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- Removed message: http://bugs.python.org/msg288062 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Changes by Amit Kumar <dtu.amit@gmail.com>: ---------- pull_requests: +106 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Nick Coghlan added the comment: 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/3337d33a4518f7ab8a7ab6c9a75b8b92ba3... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Nick Coghlan added the comment: 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/24bfe15e83c24bf2c2e2654050da8095537... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Changes by Mariatta Wijaya <mariatta.wijaya@gmail.com>: ---------- pull_requests: +553 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Mariatta Wijaya added the comment: New changeset db3deb98e969d3f43b169cd320abd46b21a10c6d by Mariatta in branch '3.6': bpo-29521 Fix two minor documentation build warnings (#41) (#83) https://github.com/python/cpython/commit/db3deb98e969d3f43b169cd320abd46b21a... ---------- nosy: +Mariatta _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Mariatta Wijaya added the comment: New changeset 38c8354f3204441f6c6bd22213b449d2d8954fcc by Mariatta in branch '3.5': bpo-29521 Fix two minor documentation build warnings (#41) (#84) https://github.com/python/cpython/commit/38c8354f3204441f6c6bd22213b449d2d89... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
STINNER Victor added the comment: New changeset 2b501866ed493758e4c4b29f0ce9b24023d910a1 by Victor Stinner in branch 'master': Travis CI: run rstlint.py in the docs job (#68) https://github.com/python/cpython/commit/2b501866ed493758e4c4b29f0ce9b24023d... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Brian Curtin added the comment: New changeset 3d707be950b387552585451071928e7b39cdfa53 by Brian Curtin (Jim DeLaHunt) in branch 'master': bpo-29521 Fix two minor documentation build warnings (#41) https://github.com/python/cpython/commit/3d707be950b387552585451071928e7b39c... ---------- nosy: +brian.curtin _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
Mariatta Wijaya added the comment: New changeset e0cba5b45a5c4bafd1ae772be52ca0d69651da24 by Mariatta in branch '2.7': [2.7] bpo-29521: Fix two minor documentation build warnings (GH-41) (GH-670) https://github.com/python/cpython/commit/e0cba5b45a5c4bafd1ae772be52ca0d6965... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29521> _______________________________________
participants (8)
-
Amit Kumar -
Brian Curtin
-
Ezio Melotti
-
Jim DeLaHunt
-
Mariatta Wijaya
-
Martin Panter
-
Nick Coghlan
-
STINNER Victor