homepage

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.

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.)

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.

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.

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.

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.

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

New changeset de553b8210882823d3df3f1ef6882eba3f8accf3 by Victor Stinner in branch '3.5':
bpo-29521 update Misc/ACKS (#111)
https://github.com/python/cpython/commit/de553b8210882823d3df3f1ef6882eba3f8accf3

New changeset 02e3357e089f37c23d0f3d1ebee9aa3d7a1492a9 by Victor Stinner in branch '3.6':
bpo-29521 update Misc/ACKS (#110)
https://github.com/python/cpython/commit/02e3357e089f37c23d0f3d1ebee9aa3d7a1492a9

New changeset 85064db281545d587992df61154e76439138319f by Victor Stinner in branch 'master':
bpo-29521 update Misc/ACKS (#106)
https://github.com/python/cpython/commit/85064db281545d587992df61154e76439138319f

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

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

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

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

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/db3deb98e969d3f43b169cd320abd46b21a10c6d

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/38c8354f3204441f6c6bd22213b449d2d8954fcc

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/2b501866ed493758e4c4b29f0ce9b24023d910a1

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/3d707be950b387552585451071928e7b39cdfa53

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/e0cba5b45a5c4bafd1ae772be52ca0d69651da24