[Distutils] Proposal: moving PyPA projects to pydoctheme

[Jon Wayne Parrott]

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/12afb52f76fc33ad43438ec6b58c7333a6186b07
and
I've restaged the preview here
http://temp.theadora.io/pypug-pydoctheme/current.html#installation-tool-recommendations
(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 at pobox.com> wrote:

> On Thu, May 25, 2017 at 7:03 PM, Jon Wayne Parrott via Distutils-SIG
> <distutils-sig at 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20170526/568341a6/attachment-0001.html>