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/

[ncoghlan]

At @merwok's suggestion, I started a python-dev thread to get the thoughts of other core developers on the suitability of this approach: https://mail.python.org/pipermail/python-dev/2017-May/148029.html

Based on @brettcannon's response there, I think the sensible approach to take would be to:

1. Create python/psf-docs-theme as the base PSF managed repo used to publish the "Official Python Documentation" theme (this will require @brettcannon to create the repo, and add @jonparrott as a contributor)
2. Add a note to the README for that repo along the lines of: "Please limit use of this theme to projects which are closely affiliated with the Python Software Foundation, and have permission from either the CPython core development team or the PSF itself for such use. For other projects looking for a simple, high contrast, pip installable Sphinx theme, we recommend the Alabaster theme used by default in Sphinx 1.3+."
3. Decide whether or not it will be practical for PyPA projects to just use that theme directly, or if we'd still want an intervening pypa/pypa-docs-theme to apply PyPA specific tweaks (I have no idea as to how the technical details of pip-installable Sphinx theming work, so I don't know how practical it is to base one theme on another at install time)

[theacodes]

@ncoghlan that sounds great. @brettcannon anything I can do to help get this process started? If we can get the repo created before Friday I can make it all happen this week.

@ncoghlan I think it's definitely worthwhile to go ahead and create pypa-docs-theme. It might just be simple inheritance from the psf theme for now, but we'll probably want some pypa-specific changes at some point. :)

[brettcannon]

I've been waiting for the discussion that @ncoghlan started to wrap up of which there was an email on the topic yesterday. Once that discussion is over I can create the repo.

[theacodes]

Thanks!

…

On Wed, May 31, 2017 at 4:02 PM Brett Cannon ***@***.***> wrote: I've been waiting for the discussion that @ncoghlan <https://github.com/ncoghlan> started to wrap up of which there was an email on the topic yesterday. Once that discussion is over I can create the repo. — 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/AAPUcwLKMmQv7oVLFWahdE4vgsxh0sgSks5r_fGSgaJpZM4NCNFU> .

[dstufft]

FWIW I think the alabaster theme looks nicer than the python docs theme, but I don't have any major objection to using either.

[ncoghlan]

@brettcannon Waiting turned out to be a good idea, as my conclusion from that discussion is that it makes more sense to call the repo python/cpython-docs-theme: https://mail.python.org/pipermail/python-dev/2017-June/148183.html

The suggested phrasing for the note in the README has also changed from what I wrote above to the following:

Note that when adopting this theme, you're also borrowing an element of the trust and credibility established by the CPython core developers over the years. That's fine, and you're welcome to do so for other Python community projects if you so choose, but please keep in mind that in doing so you're also choosing to accept some of the responsibility for maintaining that collective trust.

[brettcannon]

Since the whole thing was slightly contentious I will give it a day to wait for replies, and if nothing comes up I will create the repo (and if I have not by Monday, feel free to ping me to remind me to do so).

[brettcannon]

I have created https://github.com/python/python-docs-theme (I dropped the "c" prefix as this isn't special to the CPython implementation).

@jonparrott I made you a collaborator with write privileges.
@ncoghlan feel free to tweak the README.

[ncoghlan]

@brettcannon The note would look a little odd on an empty repo, so it probably makes more sense for @jonparrott to add it when filling in the extracted theme.

[theacodes]

Thanks @brettcannon! I should be able to make some progress on this Friday. :)

[brettcannon]

@jonparrott Great! And if the description needs a tweak or anything just let me know.

[pradyunsg]

This can be closed now that #305 has merged?

[theacodes]

Yep. :)