This is great feedback Nathaniel. :) Luckily, no nasty hacks involved. I've updated the pypa-theme to support both global and local toc so that projects can pick whichever is most appropriate for them. See the commit here https://github.com/pypa/python-packaging-user-guide/pull/305/commits/12afb52... and I've restaged the preview here http://temp.theadora.io/pypug-pydoctheme/current.html#installation-tool-reco... (caching might make it take a second, but visit any other page and you should see it). Let me know if that addresses your concerns and if you have any more! On Thu, May 25, 2017 at 10:26 PM Nathaniel Smith wrote:

...

o/ Hello everyone, I've been working on the Packaging User Guide and various discussions have come up about the theme (https://github.com/pypa/python-packaging-user-guide/issues/304) as well as the common brand for PyPA projects (https://github.com/pypa/python-packaging-user-guide/issues/62).

I'm proposing we switch PyPA projects (namely pypa.io, PyPUG, distlib,

On Thu, May 25, 2017 at 7:03 PM, Jon Wayne Parrott via Distutils-SIG wrote: pip,

...

setuptools, virtualenv, warehouse, and wheel) to match the upstream CPython docs for Python 3 (referred to as "pydoctheme").

Switching from the current readthedocs theme has a couple of advantages:

* Higher contrast and sans-serif fonts means better readability and accessibility. * Consistency with Python re-enforces that these are "official"/"blessed" tools & documentation. * A central shared theme among these projects allows us to make consistent identity modifications across projects easily.

Personally, I always use the RTD theme for my projects because it has a subtle but major advantage over every other Sphinx theme: it always provides an overview of the entire manual in the sidebar, which makes navigation much easier. With other themes I always feel like I'm lost.

Compare the sidebar here: https://packaging.python.org/current/ Versus here: http://temp.theadora.io/pypug-pydoctheme/current.html

I don't care either way about the RTD styling, pydoctheme looks nice too, but IMO this specific feature is a pretty major usability win for most projects. I believe it involves some disgusting hacks inside the RTD theme code.

-n

-- Nathaniel J. Smith -- https://vorpus.org

Further nitpick: the new version shows the whole ToC, but doesn't do anything to mark which part of it corresponds to the current page (cf the RTD theme's grey box), which makes it hard to orient oneself when looking at it. Some sort of "you are here" indicator would help :-) On Thu, May 25, 2017 at 11:08 PM, Jon Wayne Parrott wrote:

This is great feedback Nathaniel. :)

Luckily, no nasty hacks involved. I've updated the pypa-theme to support both global and local toc so that projects can pick whichever is most appropriate for them. See the commit here https://github.com/pypa/python-packaging-user-guide/pull/305/commits/12afb52... and I've restaged the preview here http://temp.theadora.io/pypug-pydoctheme/current.html#installation-tool-reco... (caching might make it take a second, but visit any other page and you should see it).

Let me know if that addresses your concerns and if you have any more!

On Thu, May 25, 2017 at 10:26 PM Nathaniel Smith wrote:

...

On Thu, May 25, 2017 at 7:03 PM, Jon Wayne Parrott via Distutils-SIG wrote:

...

o/ Hello everyone, I've been working on the Packaging User Guide and various discussions have come up about the theme (https://github.com/pypa/python-packaging-user-guide/issues/304) as well as the common brand for PyPA projects (https://github.com/pypa/python-packaging-user-guide/issues/62).

I'm proposing we switch PyPA projects (namely pypa.io, PyPUG, distlib, pip, setuptools, virtualenv, warehouse, and wheel) to match the upstream CPython docs for Python 3 (referred to as "pydoctheme").

Switching from the current readthedocs theme has a couple of advantages:

* Higher contrast and sans-serif fonts means better readability and accessibility. * Consistency with Python re-enforces that these are "official"/"blessed" tools & documentation. * A central shared theme among these projects allows us to make consistent identity modifications across projects easily.

Personally, I always use the RTD theme for my projects because it has a subtle but major advantage over every other Sphinx theme: it always provides an overview of the entire manual in the sidebar, which makes navigation much easier. With other themes I always feel like I'm lost.

Compare the sidebar here: https://packaging.python.org/current/ Versus here: http://temp.theadora.io/pypug-pydoctheme/current.html

I don't care either way about the RTD styling, pydoctheme looks nice too, but IMO this specific feature is a pretty major usability win for most projects. I believe it involves some disgusting hacks inside the RTD theme code.

-n

-- Nathaniel J. Smith -- https://vorpus.org

-- Nathaniel J. Smith -- https://vorpus.org

Thanks for working on this, Jon! On 26 May 2017 at 17:06, Nathaniel Smith wrote:

Further nitpick: the new version shows the whole ToC, but doesn't do anything to mark which part of it corresponds to the current page (cf the RTD theme's grey box), which makes it hard to orient oneself when looking at it. Some sort of "you are here" indicator would help :-)

While the subtree expansion does provide a bit of that, I do agree that some additional contrast between the expanded section and the rest of the ToC would be beneficial. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

Interestingly this doesn't have the "sticky" sidebar (eg: it moves as you scroll page) as the py3 docs have. This is my attempt to package it into a reusable theme btw: http://ionelmc.github.io/sphinx-py3doc-enhanced-theme/bare/reference/foo.bar... You probably don't want to use that directly but maybe there is stuff you can just copy from it. Thanks, -- Ionel Cristian Mărieș, http://blog.ionelmc.ro On Fri, May 26, 2017 at 7:32 PM, Jon Wayne Parrott via Distutils-SIG < distutils-sig@python.org> wrote:

Awesome, more good feedback. I've made some stylesheet adjustments to highlight both the current page (by bolding) and the current section (by coloring links). Let me know on the PR if you have alternative recommendations (leaving out the current section coloring is actually fine, IMO). Staged again here (http://temp.theadora.io/ pypug-pydoctheme/self_hosted_repository.html).

Since we mostly seem to all be in agreement, can someone who's an admin on the PyPA org create the pypa-theme repository for me?

On Fri, May 26, 2017 at 5:13 AM Nick Coghlan wrote:

...

Thanks for working on this, Jon!

On 26 May 2017 at 17:06, Nathaniel Smith wrote:

...

Further nitpick: the new version shows the whole ToC, but doesn't do anything to mark which part of it corresponds to the current page (cf the RTD theme's grey box), which makes it hard to orient oneself when looking at it. Some sort of "you are here" indicator would help :-)

While the subtree expansion does provide a bit of that, I do agree that some additional contrast between the expanded section and the rest of the ToC would be beneficial.

Cheers, Nick.

-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

On Saturday, May 27, 2017, Ionel Cristian Mărieș via Distutils-SIG < distutils-sig@python.org> wrote:

Interestingly this doesn't have the "sticky" sidebar (eg: it moves as you scroll page) as the py3 docs have. This is my attempt to package it into a reusable theme btw: http://ionelmc.github.io/sphinx-py3doc-enhanced-theme/ bare/reference/foo.bar.html

You probably don't want to use that directly but maybe there is stuff you can just copy from it.

Here's a (somewhat hackish) sticky sidebar w/: - sphinxjp.themes.basicstrap - https://pypi.python.org/pypi/sphinxjp.themes.basicstrap/ - responsive - toggle-able mobile TOC - (toggle) show :visited links - (toggle) open external links in new tab - jquery.scrollTo the current TOC heading - sphinxcontrib-srclinks - https://pypi.python.org/pypi/sphinxcontrib-srclinks - project homepage, src hyperlinks - git/hg clone commands Example: https://wrdrd.github.io/docs/tools/#sphinx https://github.com/wrdrd/docs/blob/master/Makefile - make localjs https://github.com/wrdrd/docs/tree/master/docs/_static/js - newtab.js - open links in a new tab (and store the setting in a cookie) - sidenav-affix.js - sticky sidebar - sidenav-scrollto.js - indicate current TOC heading (and scroll the TOC entry into view only of it's out of the viewport) If any of these are useful, please feel free or just let me know and I'll go ahead and package them up. ... https://github.com/yoloseem/awesome-sphinxdoc

Thanks, -- Ionel Cristian Mărieș, http://blog.ionelmc.ro

On Fri, May 26, 2017 at 7:32 PM, Jon Wayne Parrott via Distutils-SIG < distutils-sig@python.org javascript:_e(%7B%7D,'cvml','distutils-sig@python.org');> wrote:

...

Awesome, more good feedback. I've made some stylesheet adjustments to highlight both the current page (by bolding) and the current section (by coloring links). Let me know on the PR if you have alternative recommendations (leaving out the current section coloring is actually fine, IMO). Staged again here (http://temp.theadora.io/pypug -pydoctheme/self_hosted_repository.html).

Since we mostly seem to all be in agreement, can someone who's an admin on the PyPA org create the pypa-theme repository for me?

On Fri, May 26, 2017 at 5:13 AM Nick Coghlan javascript:_e(%7B%7D,'cvml','ncoghlan@gmail.com');> wrote:

...

Thanks for working on this, Jon!

On 26 May 2017 at 17:06, Nathaniel Smith javascript:_e(%7B%7D,'cvml','njs@pobox.com');> wrote:

...

Further nitpick: the new version shows the whole ToC, but doesn't do anything to mark which part of it corresponds to the current page (cf the RTD theme's grey box), which makes it hard to orient oneself when looking at it. Some sort of "you are here" indicator would help :-)

While the subtree expansion does provide a bit of that, I do agree that some additional contrast between the expanded section and the rest of the ToC would be beneficial.

Cheers, Nick.

-- Nick Coghlan | ncoghlan@gmail.com javascript:_e(%7B%7D,'cvml','ncoghlan@gmail.com'); | Brisbane, Australia

_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org javascript:_e(%7B%7D,'cvml','Distutils-SIG@python.org'); https://mail.python.org/mailman/listinfo/distutils-sig