💄 Change Sphinx theme to furo

[webknjaz]

DEMO PREVIEW: https://python-packaging-user-guide--791.org.readthedocs.build

[webknjaz]

@pradyunsg here's something to preview: https://python-packaging-user-guide--791.org.readthedocs.build/

[pradyunsg]

TBH, Furo doesn't really fit well with the structure of this documentation -- open any guide and that should provide context on why this sidebar approach can't work for this documentation.

[webknjaz]

@pradyunsg could you expand on that? I don't see anything concerning except for TOC.

[pradyunsg]

See https://python-packaging-user-guide--791.org.readthedocs.build/guides/creating-and-discovering-plugins/ for example.

[pfmoore]

@pradyunsg I just checked that link (on Chrome, on a big desktop screen) and I don't see what the issue is that you're flagging up.

[webknjaz]

@pradyunsg I don't see any problems there. Not sure what you mean to point out...

[pradyunsg]

I feel like the sidebar becomes overwhelming to navigate (which is expected, since that's what the sidebar was designed to do when there's a bit much in the docs, due to Furo's bias toward smaller documentation trees).

[pfmoore]

Hmm. If you mean that having lots of long titles for the guides means that the left hand sidebar is clumsy looking, then yes it is. But I dismissed that criticism as I see it as all part of the general "feel" of Furo, having bigger, more spaced out text. I don't like that style much, because in general I think it makes for harder navigation in text-heavy documentation, but "I don't like the look of Furo" isn't really the point here.

If you want an example in another document, I find pip's "Reference Guide" sidebar awkward (too many items, the wide spacing makes it difficult to locate items at a glance) and also the "Development -> Architecture of pip's internals" sidebar (long titles, same as here).

As I say, I don't like the style much in general, but if we're settling on it as a "PyPA look", then I don't think it's significantly worse here than in other cases. Disclaimer: I'm not a web designer, I'm just going off what I personally like and dislike, which shouldn't be given undue weight.

[pradyunsg]

I hear you and generally agree.

I feel like we actually need another layer of navigational capabilities for our (generally) larger docs, because this content is actually not structured for how Sphinx RTD theme and Furo handle navigation trees (one big tree that we can present all of). This is different from Furo's own docs, as well as various other projects that have adopted it (attrs, urllib3 being the most prominent examples).

I have some ideas for dealing with the more complex navigation trees, but I'll only be able to get to making something for those ideas after pip 20.3 (and a bit of downtime after that).

(the idea is basically mkdocs-material's tabs approach for splitting the various larger sections)

[webknjaz]

@pradyunsg anything actionable here?

[pradyunsg]

I'd hold off on this for a bit. There's a "sibling theme" for Furo that I'm working on that'll likely be a better fit. :)

[webknjaz]

@pradyunsg any progress on that other theme? I rebased this PR just in case.

[astrojuanlu]

xref python/docs-community#1 (comment) :)

[webknjaz]

cc @willingc

[willingc]

+1 to improved theme

[sinoroc]

Errors here:

• https://python-packaging-user-guide--791.org.readthedocs.build/en/791/discussions/install-requires-vs-requirements/
• https://python-packaging-user-guide--791.org.readthedocs.build/en/791/discussions/deploying-python-applications/

[pradyunsg]

@sinoroc Oooh, I missed that! Let's fix those in follow ups!

[sinoroc]

@pradyunsg So, do I understand correctly that local table of contents within the document itself (the .. contents:: directive) are not supported and cause these issues?

[jeanas]

Yes, that's it. See #1358.

[sinoroc]

@pradyunsg It seems to me like we lost the favicon in the transition. Could it be? Or is my browser playing tricks on me?

[pradyunsg]

#1360 filed for that!