[issue24832] Issue building docs with newer sphix (default theme -> classic)
New submission from R. David Murray: After doing a make clean in Doc, the built documents no longer rendered correctly. I tracked this down to the Sphinx warning I'd been ignoring for a while: WARNING: 'default' html theme has been renamed to 'classic'. Please change your html_theme setting either to the new 'alabaster' default theme, or to 'classic' to keep using the old default. Now, this seems problematic, because we don't know which version of Sphinx is going to be used to build the docs, so it doesn't seen correct to just change "inherit = default" to "inherit = classic" in tools/pydoctheme.conf. Any sphinx experts know what the correct solution is here? Do we change it and thus (IIUC) require 1.3.1 as the minimum Sphinx version? ---------- assignee: docs@python components: Documentation messages: 248285 nosy: docs@python, r.david.murray priority: normal severity: normal status: open title: Issue building docs with newer sphix (default theme -> classic) _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Carol Willing added the comment: Is the behavior different in default or 3.5 release and 2.7 release? The default branch has html_theme in Doc/conf.py https://hg.python.org/cpython/file/default/Doc/conf.py set to 'pydoctheme'. The 2.7 branch has html_theme in Doc/conf.py https://hg.python.org/cpython/file/2.7/Doc/conf.py to 'default'. Iss24400 made a recent change https://hg.python.org/cpython/rev/68996acdec6f. ---------- nosy: +willingc _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
R. David Murray added the comment: I only checked this on 3.5 and 3.6, but 3.4 is using pydoctheme, and python2.7 is using default. So presumably none of them will build using Sphinx 1.3.1. Yuri's change appears to be undoing a change he inadvertently committed, which was probably a change he made locally so he could get the docs to build because of this very problem. ---------- assignee: docs@python -> nosy: +georg.brandl, yselivanov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Carol Willing added the comment: David, Thanks for pointing this out. I totally forgot that the 2 and 3 versions use different themes :( ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Zachary Ware added the comment: Which version of Sphinx are you using? The Docs buildbot is happily building with 1.3.1 (though failing the lint check, which I missed when it started). ---------- nosy: +zach.ware _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
R. David Murray added the comment: 1.3.1. The doc build doesn't *fail*, it's just that if you try to view the built pages they don't render correctly, because there is no default.css that the pydoctheme depends on. I wonder what the web site is using for the build. Although copying default.css from an old build works (as would, presumably, copying classic.css to default.css or hardlinking it). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Changes by R. David Murray <rdmurray@bitdance.com>: ---------- title: Issue building docs with newer sphix (default theme -> classic) -> Issue building docs with newer sphinx (default theme -> classic) _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Changes by R. David Murray <rdmurray@bitdance.com>: ---------- title: Issue building docs with newer sphinx (default theme -> classic) -> Issue building viewable docs with newer sphinx (default theme -> classic) _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Zachary Ware added the comment: Ah, sorry; I missed that distinction. I can't reproduce, though: in a clean checkout of default, I just did: cd Doc/ make venv PYTHON=python3 source venv/bin/activate make html The resulting build did emit the warning about the themes, but the docs produced render just fine. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
R. David Murray added the comment: Hmm. All I do is 'make clean; make html', but I don't see why that would make a difference to the problem on point. I didn't know about this make venv thing...that must be newish? When I try it, that does indeed work. Building that way produces a 'default.css' in build/html/_static, whereas building without the venv (but with sphinx 1.3.1) does not. I have no idea why, it doesn't really make sense that that would be the case. Perhaps the experiment of using the installed sphinx to build the docs is a failure and we should just make using local copies the default again? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Benjamin Peterson added the comment: Please keep the doc build compatible with Sphinx 1.2.*. Sphinx 1.3.1 has a problem with LaTeX generation, so we can't upgrade the automated docs build to use it until 1.3.2 is released. ---------- nosy: +benjamin.peterson _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Bernie Hackett added the comment: We had the same problem with PyMongo's docs. The issue happens with Sphinx 1.3.0 and 1.3.1. It appears to be resolved in 1.3.2. The changelog includes this line (no issue number is mentioned): Add a “default.css” stylesheet (which imports “classic.css”) for compatibility. http://www.sphinx-doc.org/en/stable/changes.html#release-1-3-2-released-nov-... ---------- nosy: +behackett _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Martin Panter added the comment: After upgrading from 1.3.1 to 1.3.4, I no longer get the warning. Perhaps we can close this now? ---------- nosy: +martin.panter resolution: -> third party _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
Benjamin Peterson added the comment: We build happily with 1.3.3 on docs.python.org, so looks like everything is okay. ---------- resolution: third party -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________
participants (6)
-
Benjamin Peterson -
Bernie Hackett
-
Carol Willing
-
Martin Panter
-
R. David Murray
-
Zachary Ware