Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation uses deprecated "defindex.html" Sphinx template #73706

Closed
jdlh mannequin opened this issue Feb 10, 2017 · 13 comments
Closed

Documentation uses deprecated "defindex.html" Sphinx template #73706

jdlh mannequin opened this issue Feb 10, 2017 · 13 comments
Labels
3.7 (EOL) end of life docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@jdlh
Copy link
Mannequin

jdlh mannequin commented Feb 10, 2017

BPO 29520
Nosy @ncoghlan, @methane, @cocoatomo, @ultimatecoder, @JDLH
PRs
  • bpo-29520: Fix deprecation warning from 'defindex' template #165
  • bpo-29520: Fixing deprecation warning while building docs #170
  • [3.6] bpo-29520: fix deprecation warning from 'defindex' template #178
  • [3.5] bpo-29520: fix deprecation warning from 'defindex' template #179
  • [2.7] bpo-29520: fix deprecation warning from 'defindex' template #180
  • bpo-29520: doc: add missing dot #182
    		•
    Files
  • doc_logs_python.log
  • sphinx-1.5-pydoc.png
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
closed_at = <Date 2017-02-20.10:20:37.567>
created_at = <Date 2017-02-10.07:29:46.061>
labels = ['type-feature', '3.7', 'docs']
title = 'Documentation uses deprecated "defindex.html" Sphinx template'
updated_at = <Date 2017-02-20.10:20:37.566>
user = 'https://github.com/JDLH'

    bugs.python.org fields:

    activity = <Date 2017-02-20.10:20:37.566>
actor = 'methane'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-02-20.10:20:37.567>
closer = 'methane'
components = ['Documentation']
creation = <Date 2017-02-10.07:29:46.061>
creator = 'JDLH'
dependencies = []
files = ['46647', '46648']
hgrepos = []
issue_num = 29520
keywords = []
message_count = 13.0
messages = ['287478', '287485', '288096', '288097', '288099', '288100', '288115', '288120', '288146', '288174', '288175', '288176', '288178']
nosy_count = 6.0
nosy_names = ['ncoghlan', 'methane', 'docs@python', 'cocoatomo', 'jaysinh.shukla', 'JDLH']
pr_nums = ['165', '170', '178', '179', '180', '182']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue29520'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7']
    @jdlh
    Copy link
    Mannequin Author

    jdlh mannequin commented Feb 10, 2017

    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 bpo-2986 (sphinx-doc/sphinx#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 sphinx-doc/sphinx@45d3f2e ). 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.

    @jdlh jdlh mannequin added build The build process and cross-build 3.7 (EOL) end of life labels Feb 10, 2017
    @jdlh jdlh mannequin assigned docspython Feb 10, 2017
    @jdlh jdlh mannequin added the docs Documentation in the Doc dir label Feb 10, 2017
    @jdlh
    Copy link
    Mannequin Author

    jdlh mannequin commented Feb 10, 2017

    The other warnings in the "make html" output are the subject of http://bugs.python.org/issue29521 .

    @berkerpeksag berkerpeksag added type-feature A feature request or enhancement and removed build The build process and cross-build labels Feb 13, 2017
    @ultimatecoder
    Copy link
    Mannequin

    ultimatecoder mannequin commented Feb 19, 2017

    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!

    @methane
    Copy link
    Member

    methane commented Feb 19, 2017

    I can reproduce it with Sphinx 1.5.2.
    Additonally, "None" is shown at top.

    @methane
    Copy link
    Member

    methane commented Feb 19, 2017

    ref: sphinx-doc/sphinx#2986

    @methane
    Copy link
    Member

    methane commented Feb 19, 2017

    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.

    @jdlh
    Copy link
    Mannequin Author

    jdlh mannequin commented Feb 19, 2017

    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 sphinx-doc/sphinx#2986, it looks like the Sphinx team added the warning message at or shortly after the release of 1.5.0.

    @cocoatomo
    Copy link
    Mannequin

    cocoatomo mannequin commented Feb 19, 2017

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

    @methane
    Copy link
    Member

    methane commented Feb 19, 2017

    New changeset 3eea8c6 by GitHub in branch 'master':
    bpo-29520: doc: fix deprecation warning from 'defindex' template (GH-165)
    3eea8c6

    @methane
    Copy link
    Member

    methane commented Feb 20, 2017

    New changeset cf44d95 by GitHub in branch '2.7':
    bpo-29520: doc: fix deprecation warning from 'defindex' template (GH-180)
    cf44d95

    @methane
    Copy link
    Member

    methane commented Feb 20, 2017

    New changeset f0174c6 by GitHub in branch '3.5':
    bpo-29520: doc: fix deprecation warning from 'defindex' template (GH-179)
    f0174c6

    @methane
    Copy link
    Member

    methane commented Feb 20, 2017

    New changeset 7970cd4 by GitHub in branch '3.6':
    bpo-29520: doc: fix deprecation warning from 'defindex' template (GH-178)
    7970cd4

    @methane
    Copy link
    Member

    methane commented Feb 20, 2017

    New changeset e395c4d by GitHub in branch 'master':
    bpo-29520: doc: add missing dot (GH-182)
    e395c4d

    @methane methane closed this as completed Feb 20, 2017
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.7 (EOL) end of life docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    2 participants
    @berkerpeksag @methane