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.

classification
Title: Update devguide style to use a similar theme as Docs
Type: enhancement Stage: patch review
Components: Devguide Versions:
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: Nosy List: berker.peksag, brett.cannon, ezio.melotti, georg.brandl, lisroach, python-dev, r.david.murray, rhettinger, vstinner, willingc, zach.ware
Priority: normal Keywords: patch

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

Files
File name Uploaded Description Edit
Screen Shot 2015-04-14 at 12.42.48 PM.png willingc, 2015-04-14 16:48
devguide_theme.patch lisroach, 2016-06-30 05:03 Devguide theme patch for consistency with pydoctheme.
devguide_theme_revised.patch lisroach, 2016-07-20 05:00 Devguide theme patch for consistency with pydoctheme, updated based on feedback.
devguide_theme_revised.patch lisroach, 2016-07-20 05:06 Devguide theme patch for consistency with pydoctheme, updated based on feedback.
Messages (20)
msg240943 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-04-14 16:48
It would be helpful to update the conf.py file and dependencies to use a modified 'pydoctheme' for the devguide style. The benefits would be improved readability, a consistent look with the stdlib docs, and collapsible sidebars.

Attached is a screenshot of a quick hack of the conf.py file and the rendered devguide index.
msg240951 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2015-04-14 16:56
One benefit to having a different theme for the devguide is that it makes clear that "you're not in the standard library docs anymore".  I agree that that screenshot looks quite a bit better, though.
msg240992 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-04-14 19:23
Zach, Good point. Perhaps a different highlight color across the top would be enough to indicate that "you are in the dev guide".
msg269560 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2016-06-30 05:03
I have updated the conf.py and added a "tools" folder that contains the themes, templates, etc. to make the devguide match more closely with the pydoctheme. I altered the theme a little bit to keep the colors more consistent with the original devguide, hopefully this will retain the obvious difference between the two documents while merging some of the more beneficial items (collapsible sidebar, code highlighting, etc.). 

This is my first patch submitted to Python, so I appreciate any feedback :)
msg269563 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-06-30 08:22
This has a nice look and feel.
msg269567 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-06-30 09:45
I like the new style. I don't think that it's a big issue if people come to the /devguide/ by mistake. They should understand quickly their mistake and search for the right documentation.
msg269629 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2016-06-30 21:29
Another +1 here, looks good and has some nice improvements.

The patch needs some cleanup, though:

We don't need the extensions [1], the version switcher, or the susp-ignored file.

The templates dir needs some cleanup; we don't need the download page at all, and the indexsidebar.html template needs to be properly updated for the devguide (or removed, but updated would probably be nicer), and indexcontent.html can go away.  layout.html could stand some cleanup as well, removing the stuff that doesn't apply to the devguide.

rstlint.py can probably stay, it has a few complaints that might be nice to fix.  It would be nice to wire it into the Makefile (and make.bat) if it's staying.

tools/static/py.png does need to be copied over, though (and currently isn't in the patch); it's used in the upper left corner of the page.



With cleanup, though, I'm looking forward to this going in!


[1] it might be interesting to look into what extensions from the regular docs could be useful, particularly the 'suspicious' checker
msg270856 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2016-07-20 05:00
Thanks for the feedback!

I've cleaned up the patch, hopefully I've been able to catch all the little things that needed to be removed. 

I was able to wire in rstlint to the make.bat and makefile, so 'make check' should now work. 

I believe tools/static/py.png is included in the patch, if you are still not seeing it let me know. 


One thing I haven't been able to figure out: both the devguide and python 3 documentation have below the search bar this sentence: 
"Enter search terms or a module, class or function name. "

This sentence is not appearing below my patch's search bar, I am not sure why. Additionally, the "go" button is being generated slightly differently (in a div), causing it to appear below the search bar instead of beside it. Any ideas on how to fix this?
msg270857 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2016-07-20 05:06
Whoops, forgot to remove some errant code.
msg270861 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-07-20 09:49
New changeset 9e7b1bc15ba7 by Victor Stinner in branch 'default':
Use the same style than Python ref doc
https://hg.python.org/devguide/rev/9e7b1bc15ba7
msg270862 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-07-20 09:50
I pushed your new style, thanks. I didn't see any malware in the new Javascript nor new HTML :-)

I keep the issue open until the online doc is updated.
msg270872 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-07-20 14:02
-1

I think the current devguide theme looks fine and it would be nice to keep devguide and Python documentations use different themes.

I'd be -0 if the patch was small, but diff stat "11 files changed, 1651 insertions(+), 10 deletions(-)" is huge and it would be nice to avoid  code duplication. The current theme has some bugs and now we will have to update two different repos everytime we touch the docs.p.o theme.
msg270875 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2016-07-20 14:24
Lisa, thanks for your work and persistence on this patch. In particular, the pydoctheme's sidebar improves the user's ability to navigate through the devguide's content. Thank you!

If folks desire more distinction between the devguide and the language docs, color and styling could be tweaked in a future patch or PR.
msg270880 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-20 14:58
I think a reasonably consistent look and feel for all our docs is a good thing.  It's a "branding" kind of thing.  Differentiation by color works for me, but really I don't care about differentiating them, myself.  (I actually find it jarring that I don't get a table of contents as the main page, like I do in the rest of our docs.)
msg270884 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-07-20 15:32
Can we at least serve images and JS files (py.png -- this gives 404 now, copybutton.js, sidebar.js) from docs.python.org?

It seems like devguide_theme_revised.patch was committed accidentally: https://hg.python.org/devguide/rev/9e7b1bc15ba7#l3.3

The color of a:hover needs to be tweaked here: https://dl.dropboxusercontent.com/u/166024/devguide.png

I'd also delete rstllint.py.
msg270895 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-07-20 22:40
Berker Peksag
> -1. I think the current devguide theme looks fine and it would be nice to keep devguide and Python documentations use different themes.

I pushed the change because there were 3 positive votes and no negative vote, and I like the proposed them.


> I'd be -0 if the patch was small, but diff stat "11 files changed, 1651 insertions(+), 10 deletions(-)" is huge and it would be nice to avoid  code duplication. The current theme has some bugs and now we will have to update two different repos everytime we touch the docs.p.o theme.

Sorry but I don't know anything about Sphinx theme. If you know how to fix mentionned issues, please write a patch and/or push directly changes.


> It seems like devguide_theme_revised.patch was committed accidentally: https://hg.python.org/devguide/rev/9e7b1bc15ba7#l3.3

What do you mean? It was deliberate for me to push devguide_theme_revised.patch. I don't see strong reason in comments to not push the change.


> I'd also delete rstllint.py.

It adds a new "make check" which doesn't hurt.

Maybe it may be better to contribute to Sphinx, but again, it's short and doesn't hurt.
msg270896 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-07-20 22:59
New changeset 7d8f988522ed by Victor Stinner in branch 'default':
Issue #23951: remove devguide_theme_revised.patch
https://hg.python.org/devguide/rev/7d8f988522ed
msg270934 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-07-21 15:36
New changeset 5a19fbb8501f by Zachary Ware in branch 'default':
Issue #23951: Add missing icon
https://hg.python.org/devguide/rev/5a19fbb8501f

New changeset 0f642c1ba901 by Zachary Ware in branch 'default':
Issue #23951: Clean up rstlint makefile integration
https://hg.python.org/devguide/rev/0f642c1ba901
msg270938 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-07-21 15:58
Thanks.
msg271012 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-07-22 19:46
Moved to https://github.com/python/devguide/issues/6
History
Date User Action Args
2022-04-11 14:58:15adminsetgithub: 68139
2016-07-22 19:46:36brett.cannonsetstatus: open -> closed

nosy: + brett.cannon
messages: + msg271012

resolution: out of date
2016-07-21 15:58:46vstinnersetmessages: + msg270938
2016-07-21 15:36:20python-devsetmessages: + msg270934
2016-07-20 22:59:18python-devsetmessages: + msg270896
2016-07-20 22:40:24vstinnersetmessages: + msg270895
2016-07-20 15:32:31berker.peksagsetmessages: + msg270884
2016-07-20 14:58:57r.david.murraysetnosy: + r.david.murray
messages: + msg270880
2016-07-20 14:24:37willingcsetmessages: + msg270875
2016-07-20 14:02:14berker.peksagsetnosy: + berker.peksag
messages: + msg270872
2016-07-20 09:50:03vstinnersetmessages: + msg270862
2016-07-20 09:49:14python-devsetnosy: + python-dev
messages: + msg270861
2016-07-20 05:06:54lisroachsetfiles: + devguide_theme_revised.patch

messages: + msg270857
2016-07-20 05:00:18lisroachsetfiles: + devguide_theme_revised.patch

messages: + msg270856
2016-06-30 21:29:47zach.waresetmessages: + msg269629
stage: patch review
2016-06-30 09:45:42vstinnersetnosy: + vstinner
messages: + msg269567
2016-06-30 08:22:18rhettingersetnosy: + rhettinger
messages: + msg269563
2016-06-30 05:04:17lisroachsetfiles: + devguide_theme.patch

nosy: + lisroach
messages: + msg269560

keywords: + patch
2016-01-03 06:27:23ezio.melottisetnosy: + georg.brandl
2015-04-14 19:23:40willingcsetmessages: + msg240992
2015-04-14 16:56:37zach.waresetnosy: + zach.ware
messages: + msg240951
2015-04-14 16:48:45willingccreate