This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Issue building viewable docs with newer sphinx (default theme -> classic)
Type: Stage:
Components: Documentation Versions:
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: behackett, benjamin.peterson, docs@python, georg.brandl, martin.panter, r.david.murray, willingc, yselivanov, zach.ware
Priority: normal Keywords:

Created on 2015-08-08 16:48 by r.david.murray, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Messages (12)
msg248285 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-08-08 16:48
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?
msg248287 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-08-08 17:57
Is the behavior different in default or 3.5 release and 2.7 release? 

The default branch has html_theme in Doc/ set to 'pydoctheme'.

The 2.7 branch has html_theme in Doc/ to 'default'.

Iss24400 made a recent change
msg248293 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-08-08 19:54
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.
msg248299 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-08-08 20:52
David, Thanks for pointing this out. I totally forgot that the 2 and 3 versions use different themes :(
msg248310 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2015-08-09 02:35
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).
msg248327 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-08-09 15:54
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).
msg248346 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2015-08-10 03:20
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.
msg248357 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-08-10 13:03
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?
msg248390 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2015-08-11 05:16
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.
msg258338 - (view) Author: Bernie Hackett (behackett) Date: 2016-01-15 23:03
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.
msg258347 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-01-16 01:50
After upgrading from 1.3.1 to 1.3.4, I no longer get the warning. Perhaps we can close this now?
msg258361 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2016-01-16 05:41
We build happily with 1.3.3 on, so looks like everything is okay.
Date User Action Args
2022-04-11 14:58:19adminsetgithub: 69020
2016-01-16 05:41:10benjamin.petersonsetstatus: open -> closed
resolution: third party -> fixed
messages: + msg258361
2016-01-16 01:50:54martin.pantersetresolution: third party

messages: + msg258347
nosy: + martin.panter
2016-01-15 23:03:03behackettsetnosy: + behackett
messages: + msg258338
2015-08-11 05:16:59benjamin.petersonsetnosy: + benjamin.peterson
messages: + msg248390
2015-08-10 13:03:55r.david.murraysetmessages: + msg248357
2015-08-10 03:20:34zach.waresetmessages: + msg248346
2015-08-09 16:01:59r.david.murraysettitle: Issue building docs with newer sphinx (default theme -> classic) -> Issue building viewable docs with newer sphinx (default theme -> classic)
2015-08-09 16:01:41r.david.murraysettitle: Issue building docs with newer sphix (default theme -> classic) -> Issue building docs with newer sphinx (default theme -> classic)
2015-08-09 15:54:34r.david.murraysetmessages: + msg248327
2015-08-09 02:35:44zach.waresetnosy: + zach.ware
messages: + msg248310
2015-08-08 20:52:23willingcsetmessages: + msg248299
2015-08-08 19:54:01r.david.murraysetassignee: docs@python ->

messages: + msg248293
nosy: + georg.brandl, yselivanov
2015-08-08 17:57:34willingcsetnosy: + willingc
messages: + msg248287
2015-08-08 16:48:15r.david.murraycreate