[Distutils] Proposal: moving PyPA projects to pydoctheme

[Nathaniel Smith]

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 at 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/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



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