GeezerVison

The rendered version looks wonderful.

Would love to add sphinx_copybutton in a future PR.

Why not in this one 😉

The rendered version looks wonderful.

I added a logo, should render better. Could you double check that it looks good?

The "copy to clipboard" icons aren't loading for me in the preview (Chrome/macOS):

https://cpython-devguide--679.org.readthedocs.build/

Image address is https://cpython-devguide--679.org.readthedocs.build/#_static/copy-button.svg

The "copy to clipboard" icons aren't loading for me in the preview (Chrome/macOS):

It only happens in the preview, if you build locally they work:

Aha, okay! And they work on other pages:

https://cpython-devguide--679.org.readthedocs.build/documenting/

https://cpython-devguide--679.org.readthedocs.build/_static/copy-button.svg

So maybe just not working in the preview homepage.

CC: @pradyunsg

So maybe just not working in the preview homepage.

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.

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

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:

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.

So maybe just not working in the preview homepage.

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

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!

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.

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.

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 😅

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.

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.

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

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.

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! ^.^

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.

which doesn't work at all for large docs.

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

Compare that to this:

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. :)

@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.

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.

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?

@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!

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

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

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 ☹.

Gentle ping, as 5 weeks has already passed.

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!

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?

should I raise this at the furo repo instead?

pradyunsg/furo#24

should I raise this at the furo repo instead?

pradyunsg/furo#24

Woops, thanks for pointing that out :).

Thanks everyone! Well done 😄