[issue29521] Minor warning messages when compiling documentation

[Jim DeLaHunt]

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

----------
assignee: docs at python
components: Documentation
messages: 287480
nosy: JDLH, docs at python
priority: normal
severity: normal
status: open
title: Minor warning messages when compiling documentation
type: compile error
versions: Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue29521>
_______________________________________