Switch the theme to 'furo' #679

Yeah, I am quite sure is some artifact of the preview. I am confident they will work on the deployed version. If not, we can remove the plugin while we investigate.

hugovk · 2021-04-28T17:00:43Z

And otherwise looks good with a quick scroll through on Chrome/Android too.

hugovk · 2021-04-28T17:06:09Z

And otherwise looks good with a quick scroll through on Chrome/Android too.

And the logo looks great, but it's a bit big vertically, pushing the menu down to the corner and making it a bit small and squashed to use:

pradyunsg · 2021-04-28T17:07:56Z

And the logo looks great, but it's a bit big vertically, pushing the menu down to the corner and making it a bit small and squashed to use:

One option for handling this is making the entire sidebar scrollable. Example for how to do this is at https://pradyunsg.me/furo/customisation/sidebar/#using-html-sidebars.

pradyunsg

I suggest unsetting pygments_style = "sphinx" although that's obviously a stylistic choice for someone else to decide on. :)

pradyunsg · 2021-04-28T17:10:26Z

So maybe just not working in the preview homepage.

I think that's likely due to caching with RTD's preview website?

pradyunsg · 2021-04-28T17:17:17Z

I think that's likely due to caching with RTD's preview website?

I stand corrected! It's using the wrong link: #_static/copy-button.svg -- coming from the use of ${DOCUMENTATION.URL_ROOT} in the extension:

https://github.com/executablebooks/sphinx-copybutton/blob/d13f7d188b116b656b732bcdefd34e5d9900902e/sphinx_copybutton/_static/copybutton.js_t#L85

That's a bug to file with the extension!

pablogsal · 2021-04-28T17:18:33Z

And otherwise looks good with a quick scroll through on Chrome/Android too.

And the logo looks great, but it's a bit big vertically, pushing the menu down to the corner and making it a bit small and squashed to use:

We can make it smaller I think. That would probably fix the biggest annoyance of having it.

pablogsal · 2021-04-28T17:21:21Z

And the logo looks great, but it's a bit big vertically, pushing the menu down to the corner and making it a bit small and squashed to use:

One option for handling this is making the entire sidebar scrollable. Example for how to do this is at https://pradyunsg.me/furo/customisation/sidebar/#using-html-sidebars.

Ok, I will try that. We also need to remove the ethical adds because we cannot add those without further discussion.

Mariatta · 2021-04-28T17:56:28Z

It looks really nice, and thanks for working on this.
Though on one had I'm kinda wishing we could stick with python-docs-theme for the element of "trust" and "credibility" since that's the same theme as CPython docs. So I'm +0.5 on this 😅

Mariatta · 2021-04-28T18:08:07Z

I'm sorry, I re-read what I wrote, and it sounded like I'm saying that the new theme is not trustworthy or not credible, which is not true, and I apologize for that.
I think I just wanted to say that, I think it would be great if the theme of CPython docs (docs.python.org) and the Devguide can be the same. Perhaps that's the intention going forward?
I do think the furo theme looks real nice and modern.

pablogsal · 2021-04-28T18:55:21Z

I think I just wanted to say that, I think it would be great if the theme of CPython docs (docs.python.org) and the Devguide can be the same. Perhaps that's the intention going forward?

That's would be nice to do in the future, but for now, changing the devguide is an improvement on almost all fronts and can be used in the future as a stepping stone for changing in all other places. With this we get:

Modern theme
Responsive: I can check this on my phone.
Clear admonitions: warnings and info are clearly differentiated.
Respects dark theme options
Used already in many projects, including pip: https://pip.pypa.io/en/stable/

I understand the wish to keeps those aligned but I humbly think these benefits outweigh any possible separation: in practical terms is better for the end consumer.

pablogsal · 2021-04-28T18:57:57Z

I am sure @willingc can expand on what I said :)

pradyunsg · 2021-04-28T19:02:05Z

I do think the furo theme looks real nice and modern.

Hurray! That was the goal! ^>^

it sounded like I'm saying that the new theme is not trustworthy or not credible, which is not true, and I apologize for that.

Hehe, no need to apologize. I understood what you meant. And as the primary author of Furo, I'm probably the only person who could take offense to that. :)

I think I just wanted to say that, I think it would be great if the theme of CPython docs (docs.python.org) and the Devguide can be the same. Perhaps that's the intention going forward?

FWIW, there are similar concerns with moving packaging.python.org as well. All these sites derive a degree of credibility from the fact that they "look like the official Python docs".

FWIW, if you're thinking of adopting Furo with some large documentation set... I'd say that sort of thing that would not work, since Furo is designed with the idea of "you can get everywhere from the left sidebar" -- which doesn't work at all for large docs.

pradyunsg · 2021-04-28T19:08:37Z

If there's genuine interest in the modernization of the Python documentation and python-docs-theme (i.e. fairly major changes to look more like from-this-decade), I am very very interested in helping with that. :)

As an honest aside (rant?), I actually initially want to put effort into modernizing python-docs-theme -- which would've dribbled down to pypa-docs-theme and hence pip's documentation (which I'm a maintainer of, and whose documentation was something I wanted to be improve). However, each time in the past that I had proposed making any changes to the Python docs theme, those were shut down pretty quick with a fairly heavy hand. In a similar vein, my experience contributing to the PEPs repo was, straight-up, a bad experience. Based on how long a PR making fair straightforward improvements for the mobile experience has just sat there, I ended up deciding that it's a better investment of effort to just write a separate Sphinx theme -- which is Furo.

All this is to say, if there's something around Python documentation that I can help with, I'd be very happy to! ^.^

pablogsal · 2021-04-28T19:10:53Z

has just sat there

I think that is a bit of an overstatement, the last comment from a core dev was:

python/python-docs-theme#46 (comment)

which is 14 days ago.

Clarification: I mean this in the sense that the PR is actively being reviewed and is not abandoned or not acknowledged. Is jut that the iteration takes quite a lot.

pablogsal · 2021-04-28T19:17:07Z

which doesn't work at all for large docs.

IDK, I think it looks quite good and the navigation is not bad:

pablogsal · 2021-04-28T19:18:58Z

Compare that to this:

pradyunsg · 2021-04-28T19:20:57Z

I think that is a bit of an overstatement,

Yea, sorry, I didn't mean to imply that it was sitting unattended to -- just that it has been taking a long time. :)

pablogsal · 2021-04-28T19:21:13Z

@willingc @Mariatta @JulienPalard Unfortunately, I don't have the bandwidth to work on this if we are not sure that we are going to move forward, so I would be more comfortable if we can have confirmation that this is the way to go.

Please, see the previous discussion regarding why I think we should proceed.

willingc · 2021-04-28T21:23:57Z

A few years ago, there was a discussion that we didn't want the dev guide to be the same as the docs.python.org site. I really think a modern theme would be beneficial for many reasons especially making it responsive which is helpful for folks in countries where their access is limited and includes cell phones.

Let's do this. Let's use the Furo theme for the Docs WG and make it a high priority to move the existing theme to something responsive and work on CSS to give it a closer look and feel for the footer.

pablogsal · 2021-04-28T21:59:14Z

A few years ago, there was a discussion that we didn't want the dev guide to be the same as the docs.python.org site. I really think a modern theme would be beneficial for many reasons especially making it responsive which is helpful for folks in countries where their access is limited and includes cell phones.

I agree. I also think I am a bit frustrated that we keep prioritizing a suboptimal status quo again and again in many places based on reasons that in my opinion don't impact the user experience that much or, in the other hand, we strive to produce a perfect result that makes everything great and everyone happy and that stops any small effort that combined could have made us reach that point. This has lead to many existing efforts taking too long or not happening at all. I'm talking about moving the pep repo to sphinx, having dark themes for the python theme, a responsive design for BPO, better highlighting for code blocks... And a large list of improvements that would have objectively made the experience of our users better but at the end have never materialised because of this or they are taking too long (some times even several years).

I think we must stop this trend (not specifically with this PR for sure, but the trend in general). And the solution cannot be to promise or plan, it has to be to act and push forward, little by little, transforming imperfect improvements into a really good end goal. And this has to be done with decisiveness in places that are visible so we can leverage the momentum everywhere. Otherwise we will burn the little fuel that we have and the energy of contributors (internal or external) that have energy to propose plans and try to make them a reality. And unfortunately, I personally think this is what's currently happening.

Let's do this. Let's use the Furo theme for the Docs WG and make it a high priority to move the existing theme to something responsive and work on CSS to give it a closer look and feel for the footer.

Should I close this PR then?

willingc · 2021-04-28T22:09:29Z

@pablogsal Please leave it open. I would really like this to be merged, but I want an opportunity to build consensus with Mariatta, Ned, and Julian. Thanks!

willingc · 2021-04-28T22:11:22Z

I also completely agree that we need to be helpful for new contributors and committers. Documentation is the gateway to the future.

Mariatta · 2021-04-29T13:56:21Z

Thank you for the additional context. I was missing the background of what motivated this change, so it's really helpful to know.

JulienPalard · 2021-05-01T10:28:57Z

Yea, sorry, I didn't mean to imply that it was sitting unattended to -- just that it has been taking a long time. :)

I'm also frustrated by the slow evolution of the current theme. But I'm also particularly bad at understanding CSS (let alone writing some), this is completly foreign to me, so it has always been hard (and unapealing) for me to make those PR move forward. I'm impressed by your furo theme :)

I try to test the PRs though, and try to make them easier to test, but I often find issues (dark theme dispalying a mix of dark and light theme, responsive mode hiding the language switcher, ...) so yes, it's hard and long to reach a mergeable point ☹.

pablogsal · 2021-06-04T17:32:15Z

Gentle ping, as 5 weeks has already passed.

JulienPalard · 2021-06-04T17:54:16Z

I'm merging this, I think this is a good idea, let's move forward!

python-docs-theme is evolving, but it still lags behind and with my inexistant HTML/CSS skill I won't be of any help there.

For the "element of trust", the domain is enough for me.

Having a common style between python.org, docs.python.org, devguide.python.org, wiki.python.org, ... is something I'd like too, but we're far far away from having a common style, so this enhancement will not hurt much.

Thanks @pablogsal for the PR and thanks @pradyunsg for the theme, it looks really nice!

Fidget-Spinner · 2021-06-06T06:37:49Z

Thanks everyone for working on this! It looks much better on mobile now.

Side question: is there some way to manually toggle between dark and light themes? I noticed it automatically detects the browser's theme and chooses light/dark correspondingly, but I've gotten questions from friends with astigmatism who find the dark theme hard to read and want to toggle to the light theme without changing the browser's theme.

Sorry if this isn't the right place to bring it up, should I raise this at the furo repo instead?

pradyunsg · 2021-06-06T08:10:21Z

should I raise this at the furo repo instead?

pradyunsg/furo#24

Fidget-Spinner · 2021-06-06T09:26:39Z

should I raise this at the furo repo instead?

pradyunsg/furo#24

Woops, thanks for pointing that out :).

willingc · 2021-06-06T16:42:59Z

Thanks everyone! Well done 😄

pablogsal requested review from JulienPalard, willingc and Mariatta April 28, 2021 16:42

the-knights-who-say-ni added the CLA signed label Apr 28, 2021

pablogsal force-pushed the furo branch from 8a01741 to 37e076b Compare April 28, 2021 16:43

willingc approved these changes Apr 28, 2021

View reviewed changes

Switch the theme to 'furo'

b7824e3

pablogsal force-pushed the furo branch from 37e076b to b7824e3 Compare April 28, 2021 16:47

Add 'sphinx_copybutton' extension

ffd738d

pradyunsg reviewed Apr 28, 2021

View reviewed changes

pradyunsg mentioned this pull request Apr 28, 2021

Link to static asset is broken for code blocks in the root_doc executablebooks/sphinx-copybutton#121

Closed

willingc mentioned this pull request Apr 28, 2021

Migration of theme to modern responsive theme python/docs-community#1

Open

Merge branch 'master' into furo

4bf607c

JulienPalard merged commit d6714a4 into master Jun 4, 2021

JulienPalard deleted the furo branch June 4, 2021 17:54

This was referenced Jan 27, 2022

Broken link "Copyright" at the footer of the devguide. #653

Closed

Added copyright link for the devguide #665

Closed

AA-Turner pushed a commit to AA-Turner/devguide that referenced this pull request Jun 17, 2022

Switch the theme to 'furo' (python#679)

38fa926

hugovk mentioned this pull request Dec 23, 2022

Floating << in mobile #372

Closed

Switch the theme to 'furo' #679

Switch the theme to 'furo' #679

Conversation

pablogsal commented Apr 28, 2021 • edited

willingc left a comment

Choose a reason for hiding this comment

willingc commented Apr 28, 2021

pablogsal commented Apr 28, 2021

pablogsal commented Apr 28, 2021 • edited

hugovk commented Apr 28, 2021

pablogsal commented Apr 28, 2021

hugovk commented Apr 28, 2021

pablogsal commented Apr 28, 2021

pablogsal commented Apr 28, 2021

hugovk commented Apr 28, 2021

hugovk commented Apr 28, 2021

pradyunsg commented Apr 28, 2021

pradyunsg left a comment

Choose a reason for hiding this comment

pradyunsg commented Apr 28, 2021

pradyunsg commented Apr 28, 2021

pablogsal commented Apr 28, 2021

pablogsal commented Apr 28, 2021

Mariatta commented Apr 28, 2021

Mariatta commented Apr 28, 2021

pablogsal commented Apr 28, 2021 • edited

pablogsal commented Apr 28, 2021

pradyunsg commented Apr 28, 2021 • edited

pradyunsg commented Apr 28, 2021 • edited

pablogsal commented Apr 28, 2021 • edited

pablogsal commented Apr 28, 2021 • edited

pablogsal commented Apr 28, 2021

pradyunsg commented Apr 28, 2021

pablogsal commented Apr 28, 2021 • edited

willingc commented Apr 28, 2021

pablogsal commented Apr 28, 2021 • edited

willingc commented Apr 28, 2021

willingc commented Apr 28, 2021

Mariatta commented Apr 29, 2021

JulienPalard commented May 1, 2021

pablogsal commented Jun 4, 2021

JulienPalard commented Jun 4, 2021

Fidget-Spinner commented Jun 6, 2021

pradyunsg commented Jun 6, 2021

Fidget-Spinner commented Jun 6, 2021

willingc commented Jun 6, 2021

pablogsal commented Apr 28, 2021 •

edited

pablogsal commented Apr 28, 2021 •

edited

pablogsal commented Apr 28, 2021 •

edited

pradyunsg commented Apr 28, 2021 •

edited

pradyunsg commented Apr 28, 2021 •

edited

pablogsal commented Apr 28, 2021 •

edited

pablogsal commented Apr 28, 2021 •

edited

pablogsal commented Apr 28, 2021 •

edited

pablogsal commented Apr 28, 2021 •

edited