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@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 <rep...@bugs.python.org>
<http://bugs.python.org/issue29521>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
