New submission from Jim DeLaHunt:
When I build the documentation on the current CPython code, there is a
deprecation warning on the console.
===== (beginning of output)
% make html
sphinx-build -b html -d build/doctrees -D latex_elements.papersize= .
build/html
Running Sphinx v1.5.2
...[omitted irrelevant output]...
generating indices... genindex py-modindex
writing additional pages... download index
WARNING: Now base template defindex.html is deprecated.
search opensearch
copying images... [100%] faq/python-video-icon.png
...[omitted irrelevant output]...
build succeeded, 1 warning.
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".
There are other warnings in the output, and I'm dealing with them in a
different issue (number to follow). They are easier to fix than this one.
Diagnosis:
Sphinx config file Doc/conf.py:72 invokes the building of template
'indexcontent.html'.
Doc/tools/templates/indexcontent.html:1 contains Sphinx directive
`{% extends "defindex.html" %}`.
This invokes file sphinx/sphinx/themes/basic/defindex.html
[See
https://github.com/sphinx-doc/sphinx/blob/8ecd7ff08249739bbc6d900527fe9306592456ab/sphinx/themes/basic/defindex.html
]. Sure enough, it issues a deprecation warning.
{{ warn('Now base template defindex.html is deprecated.') }}
There's a story behind this file.
Sphinx issue 2986 (https://github.com/sphinx-doc/sphinx/issues/2986) says that
this is a very old file, from about the 0.2 version of Sphinx. It wasn't HTML 5
compatible, so they declared it obsolete and threw it out. Well, that lasted
only about two weeks. It became apparent that not only Python's docs, but
thousands of other projects, seem to rely on it. So, defindex.html was
restored, but with the deprecation warning.
Then, on 1. January 2017, Sphinx deleted defindex.html again. (See
https://github.com/sphinx-doc/sphinx/commit/45d3f2e8b279efa9d42068d4109cd97eb3f2d899
). I can only imagine that, once this change makes it into the public release
of Sphinx, Python's documentation, and that of thousands of projects, will
break again.
So, it seems like a good idea to proactively remove the dependence on this
Sphinx file, before that new Sphinx release comes out.
Options:
1. Copy the Sphinx defindex.html file into our source tree, and keep using it.
Plus points: it's simple and easy. Minus points: the Sphinx licence terms may
not permit this. And, it is not HTML5 compatible, which we might care about.
2. Identify the template which Sphinx intends as a successor to defindex.html,
and switch to using that. I've done a bit of searching, and couldn't find out
which template that might be.
3. Reimplement our Doc/tools/templates/indexcontent.html to rely on supported
Sphinx template, and replace whatever intermediate content we were using from
defindex.html with freshly-written code.
I don't have a solution in mind for this issue. I just want to get it in the
bug list, so we know about it.
----------
assignee: docs@python
components: Documentation
messages: 287478
nosy: JDLH, docs@python
priority: normal
severity: normal
status: open
title: Documentation uses deprecated "defindex.html" Sphinx template
type: compile error
versions: Python 3.7
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue29520>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
