WIP: Switch to Furo

[pradyunsg]

Basically a draft, to see how things look and to initiate the conversation about making this switch.

Furo is a shiny new Sphinx documentation theme that I've written, mostly because I was frustrated with how difficult it was to navigate within most Sphinx-based documentation.

Preview at: https://pip--9012.org.readthedocs.build/en/9012/

[pradyunsg]

@pypa/pip-committers Thoughts?

[xavfernandez]

This looks globally good (but I also find the current version ok :) )
I'm not a fan of the vertical line in listing:

from https://pip--9012.org.readthedocs.build/en/9012/reference/pip_install/#requirements-file-format
and actually prefer the current version on this point: https://pip.pypa.io/en/stable/reference/pip_install/#requirements-file-format

[xavfernandez]

There also seem to have a bug in https://pip--9012.org.readthedocs.build/en/9012/news/ :
when I start scrolling a little, the right content side bar completely jump to its end, showing the titles from versions 1.5.6 to 0.1.

[pradyunsg]

I'm not a fan of the vertical line in listing:

That's what I'm referring to in #9012 (comment). The issue is that our current theme doesn't stylize block-quotes beyond a bit of padding, so we're accidentally using them for indentation.

when I start scrolling a little, the right content side bar completely jump to its end, showing the titles from versions 1.5.6 to 0.1.

ACK. This was fixed in pradyunsg/furo@a83b902, but it's not make it into a release yet. :)

[pradyunsg]

This fixes all the concerns I’ve had with making the switch. If no one raises any new concerns, I’ll merge this tomorrow morning (~12 hours).

[hugovk]

Is the preview using the latest Furo release?

https://pip--9012.org.readthedocs.build/en/9012/

If so, should the RTD version selector be nearly tucked into the (hidden) left menu instead of at the bottom right?

[pradyunsg]

If so, should the RTD version selector be nearly tucked into the (hidden) left menu instead of at the bottom right?

No.

That doesn't work well with Furo's sidebar's design (background going into the side) + the fact that RTD doesn't really have great information about how to customise that means I'm A-OK with the right-side version thingie. Further, this is already status quo for the current theme so I wouldn't call it a blocker. :)

[hugovk]

Aha, I think I mixed up the ads fix, and also pip currently uses pypa_theme (selector visible in corner) not sphinx_rtd_theme (selector hidden in left menu). Sorry, carry on!

I checked a few pages, looks good, didn't find any problems.

---

One thing, probably not a problem, this table is no longer centred:

https://pip.pypa.io/en/stable/development/ci/#actual-testing
https://pip--9012.org.readthedocs.build/en/9012/development/ci/#actual-testing

---

Also, the "Developer tasks" and "Actual testing" tables looks a bit different to each other in any given theme, but looks like an RST/Sphinx/content thing, as the tables use different markup:

https://raw.githubusercontent.com/pypa/pip/master/docs/html/development/ci.rst

[pradyunsg]

ACK. I'll clean up the table borders in Furo soon-ish. Other than that, I don't think there's anything else to do here! Let's gooooo! :)