WIP: Add beeware.org header to Furo Sphinx theme. #3538

kattni · 2025-06-08T01:07:51Z

The BeeWare documentation pages are not connected visually with the beeware.org website. In preparation for a major restructure of the documentation, it was suggested that perhaps we could implement the beeware.org header on the docs pages. This is an initial proof of concept.

This implements the HTML injection feature in the Furo Sphinx theme, along with updates to the Sphinx configuration to enable it. I initially had the full beeware.css file from the website, but as there was already CSS present in custom.css, I grabbed my updates from the beeware file and added them to custom.

Potential issues:

This will require us to periodically update base.html if the Furo theme updates it. The sites will not stop working, but any updated features would not be present.

I have some initial questions/comments.

There is initial commented out CSS for using the BeeWare font within the docs. Is this something you want to do? Please see inline comment for specifics. Ultimately, you made a lot of change to exactly what headers look like on beeware.org, so if you're interested in doing this, I will need to grab quite a bit more from the beeware.css file, I think.
I believe we may want a few things out of the "Device specific styles" section of the beeware.css file as well. This is a proof of concept. We can optimise if we choose to continue down this path.
I had to do some shenanigans with the way things worked on mobile to get it to play nice visually. I obviously can't tell yet whether it broke anything in the process, but at least in my browser, when viewed as mobile, it seems to be working.
The changes to the color modes were both because the background colors were swapping between dark and light mode, and because the "view this page" icon was blending in when Dark mode was enabled. I grabbed those incantations directly out of the Furo theme to make them work.
I'm not sure we need all of these bootstrap files. I can obviously remove any superfluous content. EDIT: Also this is the latest Bootstrap, which I'm assuming we may not want to deal with.
I also don't know if we need all the bees. I can remove any superfluous bees as well.

PR Checklist:

All new features have been tested
All new features have been documented
I have read the CONTRIBUTING.md file
I will abide by the code of conduct

kattni · 2025-06-08T01:09:06Z

docs/_static/custom.css

+/* For continuity, we may want to enable the following: */
+/*.page h1, .page h2, .page h3, .page h4, .page h5, .page h6 {*/
+/*  font-family: 'Cutive', serif;*/
+/*}*/
+
+/*.sidebar-brand-text {*/
+/*  font-family: 'Cutive', serif;*/
+/*}*/


If you want the docs to have a similar feel to the beeware.org website, it may be prudent to add this in, as well as the more detailed header-bits from beeware.css.

kattni · 2025-06-08T01:14:34Z

Oof. The spelling check on pre-commit is hosing the Bootstrap files. I'm not sure how to fix that. It looks like RtD is building regardless. So, we can sort that on the other end of this.

freakboy3742 · 2025-06-09T01:22:26Z

Potential issues:

This will require us to periodically update base.html if the Furo theme updates it. The sites will not stop working, but any updated features would not be present.

Acknowledged - but that seems manageable. We can do a preview whenever the furo theme updates and confirm any issues.

I have some initial questions/comments.

There is initial commented out CSS for using the BeeWare font within the docs. Is this something you want to do? Please see inline comment for specifics. Ultimately, you made a lot of change to exactly what headers look like on beeware.org, so if you're interested in doing this, I will need to grab quite a bit more from the beeware.css file, I think.

This definitely appeals as a stylistic consistency tweak. If we can make it work technically, it seems worth it.

IIRC most of the header extras are to deal with the fact that the hinting on the Cutive font is... weird (as in - the fonts declared bounding box isn't the extents of the characters), and so additional padding is needed to compensate without the page looking overly compressed in places.

I believe we may want a few things out of the "Device specific styles" section of the beeware.css file as well. This is a proof of concept. We can optimise if we choose to continue down this path.

I had to do some shenanigans with the way things worked on mobile to get it to play nice visually. I obviously can't tell yet whether it broke anything in the process, but at least in my browser, when viewed as mobile, it seems to be working.

The changes to the color modes were both because the background colors were swapping between dark and light mode, and because the "view this page" icon was blending in when Dark mode was enabled. I grabbed those incantations directly out of the Furo theme to make them work.

Ack - I'm sure we'll find other tweaks and edge cases as we go, but as a first pass, what you've got here seems well inside the bounds of "acceptable shenanigans", and looks great.

I'm not sure we need all of these bootstrap files. I can obviously remove any superfluous content. EDIT: Also this is the latest Bootstrap, which I'm assuming we may not want to deal with.

This was my immediate thought as well. If we can't link directly to the Bootstrap CDN (and I can't remember why I/we did that, other than not trusting the CDN at some point), we should be able to rely on serving the content https://beeware.org. At the very least, serving from beeware.org would guarantee that we'll have the same versions of the CSS rendering the header on both sites.

I also don't know if we need all the bees. I can remove any superfluous bees as well.

One can never have too many bees. 🤣

But yes, I'd be surprised if we need all of those - The only usage should be favicons, plus the icon in the header bar; it's entirely possibly you can get away with just the -32 variant.

freakboy3742 · 2025-06-09T01:24:54Z

Gah - posted that early - I wanted to add an additional overall comment:

Overall - this looks great. There's some minor tweaks and tuning to be done (as you've acknowledged), but I think this is a great visual consistency improvement.

Other than the general tweaks and things you've already flagged, my only other comment is that we need to find a way to provide a link to the GitHub page in the sidebar somewhere (possibly 2 links - one for "source", and one for "issues").

kattni · 2025-06-09T02:50:32Z

Thank you. I'm quite pleased with it.

IIRC most of the header extras are to deal with the fact that the hinting on the Cutive font is... weird (as in - the fonts declared bounding box isn't the extents of the characters), and so additional padding is needed to compensate without the page looking overly compressed in places.

This may have been the source of my CSS nightmare in getting this to work. Regardless, I grabbed the entirety of the header settings from beeware.css, put them into custom, and the site renders more nicely than it does without them.

This was my immediate thought as well. If we can't link directly to the Bootstrap CDN (and I can't remember why I/we did that, other than not trusting the CDN at some point), we should be able to rely on serving the content https://beeware.org. At the very least, serving from beeware.org would guarantee that we'll have the same versions of the CSS rendering the header on both sites.

This hadn't occurred to me. It is now pulling from beeware.org. Bootstrap files have been removed.

Superfluous bees also removed.

Other than the general tweaks and things you've already flagged, my only other comment is that we need to find a way to provide a link to the GitHub page in the sidebar somewhere (possibly 2 links - one for "source", and one for "issues").

This has been added. CSS can obviously be tweaked as desired.

freakboy3742

I've flagged a couple of things inline that stood out from a quick inspection, but otherwise - this is definitely on the right track.

docs/conf.py

freakboy3742 · 2025-06-09T05:16:46Z

docs/_templates/sidebar/brand.html

+enough with Sphinx that you know what you're doing, or landed here from that
+documentation page.
+
+Hope your day's going well. :)


🤣

Is this your doing, or Pradyuns?

Entirely Pradyun's. It exists in all the files that you can customise through the Furo config, as an attempt to avoid you unnecessarily doing what we're doing. It is necessary for us, so here we are. Probably not worth removing, as any future diff would include it and show up as a change to be updated. That said, I can obviously remove it if you prefer.

Oh no - keep it in. If someone is elbow deep in this file, they deserve a little pick me up :-)

freakboy3742 · 2025-06-09T05:19:10Z

docs/_templates/header.html

+ <div class="collapse navbar-collapse" id="navbarsDefault">
+    <ul class="navbar-nav mr-auto">
+      <li class="nav-item">
+        <a class="nav-link" href="https://beeware.org/about">About</a>


Observation - these render on beeware.org as "unselected" unless it's the current page. I'm pretty sure we can just render projects (or Docs, if that's where it ends up) as permanently selected, and all others as unselected.

freakboy3742 · 2025-06-09T05:22:21Z

docs/_templates/header.html

+    </button>
+  <div class="nav-top">
+    <div class="navbar-brand-block">
+      <a class="navbar-brand" href="https://beeware.org"><img class="mx-2" src="/_static/images/brutus-32.png">BeeWare</a>


This isn't rendering on the RTD preview... I suspect because the root URL for RTD won't have this. Don't know if there's a better fix for this, and maybe we just have to live with it.

The other problem with troubleshooting this is that it renders in testing. So I would have to start making changes, pushing them, and seeing whether RtD shapes up. I'm ok with doing this, but not unless you confirm you want me to. Please let me know your thoughts.

I'm OK with this being a "known issue" with testing. We already have analogous issues with font-awesome icons; as long as we know the limitation exists, we can work around it.

I was more hoping there might be a "{{ root_url }}" template piece that could be used - but if there isn't, that's fine.

I didn't know this was a thing. It renders locally with the latest addition. We'll see if it works with RtD.

Oh - I have no idea if {{root_url}} actually exists... it may be working locally because "undefined variable" renders as "" in Jinja.

Oh fair enough. I'll dig a bit further...

So RtD evidently automatically supplies a html_baseurl, which can also be manually set in conf.py. I can't find any reasonable information about actually using it in HTML or Jinja. If you have any suggestions, I'm happy to try them. I tried {{ html_baseurl }} but, as you said, it'll work locally if it is undefined. So I didn't bother pushing that change.

freakboy3742 · 2025-06-09T05:25:20Z

docs/_templates/base.html

+    {# Custom JS #}
+    {%- block regular_scripts -%}
+    <script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script>
+    <script src="https://beeware.org/static/bootstrap/js/bootstrap.min.js"></script>


From the look of the javascript console when running locally,=, there's another JS file needed here (popper.js)

freakboy3742 · 2025-06-09T05:25:51Z

docs/_templates/base.html

+    {%- endblock -%}
+
+    <!-- Font Awesome -->
+    <script src="https://kit.fontawesome.com/078c86a30a.js" crossorigin="anonymous"></script>


Mental note that I may need to modify my font-awesome domain permission here.

freakboy3742 · 2025-06-09T05:29:38Z

docs/_static/custom.css

+.github-links {
+    font-family: 'Cutive', serif;
+    padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);
+    font-size: 1.25em;


Not sure we need this level of size emphasis; the link existing (maybe with a font-awesome Github icon as well?) is probably enough.

The rest of the ToC tree is set to be smaller than the standard unset font size. I realised after the fact, that these two screenshots look really similar. I promise they are different.

Do you want it left to its own devices, which is shown in the first screenshot?

Or would you prefer I make it the same size as the ToC tree, shown in the second screenshot? It uses a variable to do this, the reuse of which seems to be working successfully.

Further, two questions:

Do you want it Cutive or do you want it to match the ToC tree font?

I tried to add a Font Awesome icon, and I'm apparently unclear on doing so. Is this related to the permissions thing you mention in another comment?

I'd go with ToC tree sizing, but we might as well use Cutive to make it stand out a bit.

As for the font-awesome icon... I've modified the config so that RTD builds and toga.readthedocs.io should have permission to load. Locally, localhost is allowed to load... but 127.0.0.1 isn't, apparently.

freakboy3742 · 2025-06-09T05:32:41Z

docs/_static/custom.css

+}
+
+.main {
+    margin-top: 1em;


I think this is leading to a weird gap with the toc drawer.

I'm uncertain why I included this. Removing.

freakboy3742 · 2025-06-09T05:33:00Z

docs/_static/custom.css

+}
+
+.sidebar-drawer, .toc-drawer {
+    padding-top: 3em;


This is also contributing to the toc drawer spacing issue.

This is to compensate for the header height on smaller displays. I updated it to apply only in the scenario when it is necessary.

This reverts commit aefa04f.

Add beeware.org header to Furo Sphinx theme.

b354dbc

kattni commented Jun 8, 2025

View reviewed changes

Formatting.

5274ab1

Add sidebar links, remove files.

84710d0

freakboy3742 requested changes Jun 9, 2025

View reviewed changes

kattni added 7 commits June 9, 2025 16:46

Add popper.js script.

8f4e7eb

Remove bootstrap CSS from Sphinx config.

8ca6348

Render 'Projects' as selected.

cdb33c5

Setting now only applies to smaller displays.

da7e368

Use root_url for bee RtD rendering.

aefa04f

Revert "Use root_url for bee RtD rendering."

cfa670e

This reverts commit aefa04f.

Add GitHub icons, update font size.

b35ab94

Uh oh!

WIP: Add beeware.org header to Furo Sphinx theme. #3538

Are you sure you want to change the base?

WIP: Add beeware.org header to Furo Sphinx theme. #3538

Uh oh!

Conversation

kattni commented Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kattni commented Jun 8, 2025

Uh oh!

freakboy3742 commented Jun 9, 2025

Uh oh!

freakboy3742 commented Jun 9, 2025

Uh oh!

kattni commented Jun 9, 2025

Uh oh!

freakboy3742 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kattni Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kattni Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kattni commented Jun 8, 2025 •

edited

Loading

kattni Jun 9, 2025 •

edited

Loading

kattni Jun 9, 2025 •

edited

Loading