pypa/pypa-docs-theme

Common base Sphinx theme for PyPA projects

pypa-docs-theme's Issues

Update footer text

The PSF staff has requested we update:

The Python Software Foundation is a non-profit corporation. Please donate.

to:

The PyPA is a fiscal sponsoree of the Python Software Foundation, a US 501(c)(3) public charity (Federal Tax ID number is 04-3594598). Please donate.

Improving the Sidebar TOC

As it stands, the Table of Contents in the sidebar looks a little weird. While it does provide everything that it should, the way it is currently styled does not really feel polished.

I feel that there's inconsistent spacing, colours are used in a slightly confusing manner and text styling could be used for adding emphasis.

Limit body / site width?

Text taking up the whole screen makes it so much harder to read and process. Honestly even though I can see why you want to integrate the branding with python.org, it kinda sucks that all the UX advantages carefully designed into RTD has to go with it.

This is one of the no-brainer things that the RTD theme gets right. (And, I guess, that python.org still gets horribly wrong)

I'd advocate something like

div.body {
    max-width: 60em;
}

body {
    max-width: 80em;
}

Which looks like

Tracking which PyPA projects have switched

Would it make sense to keep track of which PyPA projects switch over to this theme, here or in the README?

Quick Search's "Go" Button is not properly placed/padded

The button is below the text box. I guess if it's on the same line or padded a bit, it'll look nicer?

Change base theme to Furo?

I've been spending a lot of time around Sphinx documentation stuff lately, and have a suggestion to make regarding our documentation theme (partly from my recent experience revamping pypa/packaging.python.org#627).

Suggestion: Let's switch to Furo for our base theme here. I think it'll help our documentation overall (especially pip and packaging.python.org), since it's better at surfacing the documentation structure and has better navigational capabilities throughout.

Pros:

• Provides structured, clear sidebar navigation.
• Responsive!
• Has a fairly more "modern" design.
• Has a right sidebar that provides in-page navigation.
• Dark mode. :)

Cons:

• Not python-docs-theme, which distances us from CPython documentation.

/cc @ncoghlan @dstufft @theacodes since they were fairly active in the original discussion for the creation of this theme.

Publish to PyPI

Any reason this hasn't been done already? Just a lack of resources?

Donation link in the footer of the *Packaging User Guide* is not visible

In the footer of the Packaging User Guide, there is a link for donations:

The Python Software Foundation is a non-profit corporation. Please donate.

but for me it is almost always obscured by a Read The Docs overlay element as can be seen in the following screenshot:

References:

• https://docs.readthedocs.io/en/stable/flyout-menu.html

Related:

• pypa/packaging.python.org#1230
• #21

Migrate PyPA projects to this theme

High priority:

• pip (pypa/pip#4758)
• setuptools
• virtualenv
• twine
• pypa.io (pypa/pypa.io#20)
• warehouse

Lower priority:

• pipfile
• packaging
• wheel (bitbucket)
• pkg_resources
• distlib (bitbucket)

Declare the parallelism support via sphinx extension metadata

Basically, the setup() function here should return a dict with a few keys.

Example: https://github.com/sphinx-contrib/sphinxcontrib-towncrier/blob/ff31e93/src/sphinxcontrib/towncrier/__init__.py#L183-L187.

Motivation: if you run Sphinx in a parallel mode (using -j auto CLI option), it explodes with:

Warning, treated as error:
the pypa_theme extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit