Consider switching themes

[theacodes]

(This is my first controversial idea for this project, so by all means tell me to forget it).

Sphinx now uses the Alabaster theme by default. In my opinion, Alabaster's high-contrast, large amount of whitespace, and typography lends itself to be far more readable especially for prose documentation.

I moved urllib3's documentation to Alabaster and it's largely been positively received. I also use a variant in the documentation for several other projects (nox and google-auth).

Is anyone opposed to us switching?

[ncoghlan]

+1 in principle from me (as Alabaster is also closer to the current theming of the main Python documentation), but in the discussion at #62 @qwcode was keen to maintain theming consistency across the PyPA projects, and I think he has a valid point.

In addition to packaging.python.org, the consistency in theming currently covers:

• https://www.pypa.io/
• https://pip.pypa.io/
• https://virtualenv.pypa.io/
• https://warehouse.pypa.io/
• https://wheel.readthedocs.io/

That said, there are a few packaging related projects that don't use the default RTD theme:

• https://setuptools.readthedocs.io/en/latest/
• https://pythonhosted.org/distlib/
• https://twine.readthedocs.io/en/latest/

[dstufft]

I don't have any problem in switching the other documention to alabaster (www, pip, virtualenv, warehouse). The rest would need to ask their main maintainers.

[ncoghlan]

Paging @dholth for wheel, @jaraco for setuptools, and @vsajip for distlib.

Folks, what do you think of the idea of switching to the new default Alabaster Sphinx theme for the PyPA and PyPA-related project documentation?

[vsajip]

I don't have very strong views about using Alabaster, though I do prefer sans-serif fonts for body text in documentation. Alabaster doesn't have this as a default.

IMO sans-serif fonts make documentation seem less fusty and are considered by some to be better for accessibility.

I note that @jonparrott's Alabaster variant that he mentioned above does use sans-serif fonts for body text.

Also, Alabaster doesn't use all of the available horizontal space, though perhaps that's a less important issue, as many people don't like to read very long lines of text.

The distlib docs will use the default Sphinx theme unless overridden with e.g. DISTLIB_DOC_THEME=pydoc make html, which I used for the pythonhosted docs. Hence, on RTD, distlib docs appear with the default RTD theme.

I agree that consistency would be nice, and my ideal would be an Alabaster-like theme (in terms of colours, layout) with sans-serif body text.

[theacodes]

IMO sans-serif fonts make documentation seem less fusty and are considered by some to be better for accessibility.

I'm obviously +1 on sans serif fonts but I was trying to do one thing at a time. :)

[jaraco]

Fine by me; @jonparrott, would you be willing to submit a PR to setuptools? I'm not sure what needs to be done, maybe just remove the html_theme in conf.py and remove the _theme/nature folder? That's what I would try first, not having spent any time understanding Sphinx themes.

[theacodes]

Yes, I can submit a PR to setuptools as well.

…

On Mon, Apr 24, 2017 at 10:30 AM Jason R. Coombs ***@***.***> wrote: Fine by me; @jonparrott <https://github.com/jonparrott>, would you be willing to submit a PR to setuptools? I'm not sure what needs to be done, maybe just remove the html_theme in conf.py and remove the _theme/nature folder? That's what I would try first, not having spent any time understanding Sphinx themes. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#304 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUc7ZNx-x6aYQdYGYIkETfaeXid9oWks5rzNwqgaJpZM4NCNFU> .

[theacodes]

After a conversation with @ncoghlan over on #305, it seems like switching to the Python 3 theme might actually be a better choice for consistent identity across PyPA and Python projects (#62).

The Python 3 theme offers the same benefits as Alabaster - high contrast, legible fonts, and overall cleanliness. It has the added benefit of being consistent with the Python documentation.

I'm gonna update #305 to use that, there is one drawback - the pydoctheme isn't current distributed as a separate package. I can address that later, but I want to get a preview of what this project would look like with that theme over to you all and the distutils-sig@ mailing list.

[vsajip]

I prefer the pydoc theme myself, it's what I used for the distlib docs hosted at
https://pythonhosted.org/distlib/