classification
Title: Documentation uses deprecated "defindex.html" Sphinx template
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: JDLH, cocoatomo, docs@python, inada.naoki, jaysinh.shukla, ncoghlan
Priority: normal Keywords:

Created on 2017-02-10 07:29 by JDLH, last changed 2017-02-20 10:20 by inada.naoki. This issue is now closed.

Files
File name Uploaded Description Edit
doc_logs_python.log jaysinh.shukla, 2017-02-19 02:57
sphinx-1.5-pydoc.png inada.naoki, 2017-02-19 03:25
Pull Requests
URL Status Linked Edit
PR 165 merged inada.naoki, 2017-02-19 04:17
PR 170 closed jaysinh.shukla, 2017-02-19 07:25
PR 178 merged inada.naoki, 2017-02-19 17:11
PR 179 merged inada.naoki, 2017-02-19 17:12
PR 180 merged inada.naoki, 2017-02-19 17:13
PR 182 merged inada.naoki, 2017-02-20 00:20
Messages (13)
msg287478 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-10 07:29
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.
msg287485 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-10 08:48
The other warnings in the "make html" output are the subject of http://bugs.python.org/issue29521 .
msg288096 - (view) Author: Jaysinh shukla (jaysinh.shukla) * Date: 2017-02-19 02:57
Hello Jim,
    I tried to run `make html` on `/Doc` directory at latest master. I was not able to reproduce this warning message. I am attaching console output I got while building the documentation with this issue. I request you to check that once. Will you re-install the dependancy and check for this issue once again? Many thanks!
msg288097 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-19 03:25
I can reproduce it with Sphinx 1.5.2.
Additonally, "None" is shown at top.
msg288099 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-19 03:30
ref: https://github.com/sphinx-doc/sphinx/issues/2986
msg288100 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-19 04:20
Could docs.python.org use new Sphinx, after fix this issue?

Travis checks doc with Sphinx 1.5.2, but docs.python.org seems using 1.3.3.  It's too old.
msg288115 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-19 07:16
Jaysinh, thank you for checking.  From your log, I see you are using Sphinx version 1.3.6.  I am seeing this problem with Sphinx version 1.5.2.  I think you need Sphinx 1.5.2 or later to see the warning message.

I notice my original bug description didn't specify a Sphinx version. Now we know that it needs to be a fairly recent version of Sphinx.

From the discussion in https://github.com/sphinx-doc/sphinx/issues/2986, it looks like the Sphinx team added the warning message at or shortly after the release of 1.5.0.
msg288120 - (view) Author: tomo cocoa (cocoatomo) Date: 2017-02-19 08:35
As for CPython documents, these uses only one assignment statement (``{% set ... %}``) [1]_, one h1 element and one p element [2]_ of defindex.html.
These fragments are used to generate following sentences::

   Python 3.6.0 documentation

   Welcome! This is the documentation for Python 3.6.0, last updated Feb 19, 2017. 

.. [1] https://github.com/sphinx-doc/sphinx/blob/8ecd7ff08249739bbc6d900527fe9306592456ab/sphinx/themes/basic/defindex.html#L11

.. [2] https://github.com/sphinx-doc/sphinx/blob/8ecd7ff08249739bbc6d900527fe9306592456ab/sphinx/themes/basic/defindex.html#L13-L18


Therefore, I suggest that we should make indexcontent.html extend layout.html directly and insert the jinja2 code into indexcontent.html in order to generate the sentences above
(which is much the same option as mixture of JDLH's option 1 and 3).

After I wrote this comment, I notice inada.naoki had created `pull request #165 <https://github.com/python/cpython/pull/165>`_.
msg288146 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-19 17:07
New changeset 3eea8c67fa870c6e2b7a521d292afe7fe3e95f58 by GitHub in branch 'master':
bpo-29520: doc: fix deprecation warning from 'defindex' template (GH-165)
https://github.com/python/cpython/commit/3eea8c67fa870c6e2b7a521d292afe7fe3e95f58
msg288174 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-20 00:45
New changeset cf44d957ec177be62f5349ef88515190dcfccbd6 by GitHub in branch '2.7':
bpo-29520: doc: fix deprecation warning from 'defindex' template (GH-180)
https://github.com/python/cpython/commit/cf44d957ec177be62f5349ef88515190dcfccbd6
msg288175 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-20 00:46
New changeset f0174c69b7b8bd27ee32d96e890d665da29472af by GitHub in branch '3.5':
bpo-29520: doc: fix deprecation warning from 'defindex' template (GH-179)
https://github.com/python/cpython/commit/f0174c69b7b8bd27ee32d96e890d665da29472af
msg288176 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-20 00:46
New changeset 7970cd483346dfd7723da214fb27399ecc574095 by GitHub in branch '3.6':
bpo-29520: doc: fix deprecation warning from 'defindex' template (GH-178)
https://github.com/python/cpython/commit/7970cd483346dfd7723da214fb27399ecc574095
msg288178 - (view) Author: INADA Naoki (inada.naoki) * (Python committer) Date: 2017-02-20 01:22
New changeset e395c4dbe19115aaab315c2a113b172e9fef307a by GitHub in branch 'master':
bpo-29520: doc: add missing dot (GH-182)
https://github.com/python/cpython/commit/e395c4dbe19115aaab315c2a113b172e9fef307a
History
Date User Action Args
2017-02-20 10:20:37inada.naokisetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2017-02-20 01:22:31inada.naokisetmessages: + msg288178
2017-02-20 00:46:49inada.naokisetmessages: + msg288176
2017-02-20 00:46:26inada.naokisetmessages: + msg288175
2017-02-20 00:45:58inada.naokisetmessages: + msg288174
2017-02-20 00:20:01inada.naokisetpull_requests: + pull_request151
2017-02-19 17:13:51inada.naokisetpull_requests: + pull_request147
2017-02-19 17:12:47inada.naokisetpull_requests: + pull_request146
2017-02-19 17:11:41inada.naokisetpull_requests: + pull_request145
2017-02-19 17:07:34inada.naokisetmessages: + msg288146
2017-02-19 13:05:23berker.peksagsetstage: needs patch -> patch review
2017-02-19 08:35:28cocoatomosetnosy: + cocoatomo
messages: + msg288120
2017-02-19 07:25:00jaysinh.shuklasetpull_requests: + pull_request136
2017-02-19 07:24:47jaysinh.shuklasetnosy: + ncoghlan
2017-02-19 07:16:16JDLHsetmessages: + msg288115
2017-02-19 04:20:42inada.naokisetmessages: + msg288100
2017-02-19 04:17:06inada.naokisetpull_requests: + pull_request128
2017-02-19 03:30:12inada.naokisetmessages: + msg288099
2017-02-19 03:25:36inada.naokisetfiles: + sphinx-1.5-pydoc.png
nosy: + inada.naoki
messages: + msg288097

2017-02-19 02:57:32jaysinh.shuklasetfiles: + doc_logs_python.log
nosy: + jaysinh.shukla
messages: + msg288096

2017-02-13 18:55:10berker.peksagsetstage: needs patch
type: compile error -> enhancement
versions: + Python 3.5, Python 3.6
2017-02-10 08:48:28JDLHsetmessages: + msg287485
2017-02-10 07:29:46JDLHcreate