Proposal: moving PyPA projects to pydoctheme
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.
This work has been started on PyPUG ( https://github.com/pypa/python-packaging-user-guide/pull/305#issuecomment-30...). I have staged a build of PyPUG using the new theme here ( http://temp.theadora.io/pypug-pydoctheme/index.html). Please take a look and comment on github with any concerns, and by all means tell me I'm crazy for trying to do this. :)
If the primary maintainers of these projects all agree, I will create the theme package and submit PRs to all the projects to do this migration. You'll only need to approve. From what I understand those people are @dstufft, @pfmoore, @jaraco, @vsajip, @dholth, and @ncoglan, but please let me know if I missed anyone (I'm still new!)
Thanks!
On Thu, May 25, 2017 at 7:03 PM, Jon Wayne Parrott via Distutils-SIG distutils-sig@python.org 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
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 njs@pobox.com wrote:
On Thu, May 25, 2017 at 7:03 PM, Jon Wayne Parrott via Distutils-SIG distutils-sig@python.org 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
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 jonwayne@google.com 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 njs@pobox.com wrote:
On Thu, May 25, 2017 at 7:03 PM, Jon Wayne Parrott via Distutils-SIG distutils-sig@python.org 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
Thanks for working on this, Jon!
On 26 May 2017 at 17:06, Nathaniel Smith 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.
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 ncoghlan@gmail.com wrote:
Thanks for working on this, Jon!
On 26 May 2017 at 17:06, Nathaniel Smith 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 | 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 ncoghlan@gmail.com wrote:
Thanks for working on this, Jon!
On 26 May 2017 at 17:06, Nathaniel Smith 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 | Brisbane, Australia
Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
I'm not seeing the sticky sidebar in the Python 3 docs? https://docs.python.org/3/library/stdtypes.html
On Sat, May 27, 2017 at 4:51 AM Ionel Cristian Mărieș contact@ionelmc.ro 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...
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 ncoghlan@gmail.com wrote:
Thanks for working on this, Jon!
On 26 May 2017 at 17:06, Nathaniel Smith 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 | Brisbane, Australia
Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
On Thu, Jun 1, 2017 at 1:06 AM, Jon Wayne Parrott jonwayne@google.com wrote:
I'm not seeing the sticky sidebar in the Python 3 docs?
Hmmmm. It appears that sidebar.js is part of the sphinx base theme, not sure what's going on in the python3 docs anymore ...
Thanks, -- Ionel Cristian Mărieș, http://blog.ionelmc.ro
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 <ncoghlan@gmail.com javascript:_e(%7B%7D,'cvml','ncoghlan@gmail.com');> wrote:
Thanks for working on this, Jon!
On 26 May 2017 at 17:06, Nathaniel Smith <njs@pobox.com 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
On 26 May 2017 at 06:26, Nathaniel Smith njs@pobox.com wrote:
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.
This was a concern for me, too - thanks for bringing it up - and honestly, my only real reservation about the new theme. It looks like Jon has addressed it, so personally, I'm happy with the proposed new theme now.
Paul
This looks fine to me.
On May 25, 2017, at 10:03 PM, Jon Wayne Parrott via Distutils-SIG distutils-sig@python.org 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 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 https://github.com/pypa/python-packaging-user-guide/issues/62).
I'm proposing we switch PyPA projects (namely pypa.io http://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.
This work has been started on PyPUG (https://github.com/pypa/python-packaging-user-guide/pull/305#issuecomment-30... https://github.com/pypa/python-packaging-user-guide/pull/305#issuecomment-304169735). I have staged a build of PyPUG using the new theme here (http://temp.theadora.io/pypug-pydoctheme/index.html http://temp.theadora.io/pypug-pydoctheme/index.html). Please take a look and comment on github with any concerns, and by all means tell me I'm crazy for trying to do this. :)
If the primary maintainers of these projects all agree, I will create the theme package and submit PRs to all the projects to do this migration. You'll only need to approve. From what I understand those people are @dstufft, @pfmoore, @jaraco, @vsajip, @dholth, and @ncoglan, but please let me know if I missed anyone (I'm still new!)
Thanks! _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
— Donald Stufft
participants (7)
-
Donald Stufft -
Ionel Cristian Mărieș -
Jon Wayne Parrott -
Nathaniel Smith -
Nick Coghlan -
Paul Moore -
Wes Turner