[Distutils] Proposal: moving PyPA projects to pydoctheme

[Nathaniel Smith]

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