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.

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.

Zach, Good point. Perhaps a different highlight color across the top would be enough to indicate that "you are in the dev guide".

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 :)

This has a nice look and feel.

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.

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

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?

Whoops, forgot to remove some errant code.

New changeset 9e7b1bc15ba7 by Victor Stinner in branch 'default':
Use the same style than Python ref doc
https://hg.python.org/devguide/rev/9e7b1bc15ba7

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.

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

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.

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

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.

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.

New changeset 7d8f988522ed by Victor Stinner in branch 'default':
Issue #23951: remove devguide_theme_revised.patch
https://hg.python.org/devguide/rev/7d8f988522ed

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

Thanks.

Moved to https://github.com/python/devguide/issues/6