Modernise / redesign the docs theme #196
Conversation
Note that to minimise the complexity of the docker compose file, this slightly changes the CLI command to run a one-time build.
As we are using the search built into ReadTheDocs.
I don't think we need the clutter of a separate "Show Source" if we have the (much more useful) "Edit on Github" button.
The header links may not be what we want long-term, but replicate the current site. The footer links need to be specified at least as an empty value to override the defaults from the wagtail theme.
The main site toctree in guides.rst is hidden because we don't want that to be rendered on the guides page. Sphinx Wagtail Theme currently only includes a sidebar nav for visible toctrees - it would be possible to make this a theme option but for now override their template. Note that there is now some overlap between the side navigation and the header links.
Paras have a bottom margin by default, but this causes a lopsided padding in the shaded background of an admonition.
The default theme doesn't have any minimum height, so the footer sits directly below the minimum content height with whitespace below. Use a vertical flex to ensure it always sits at (or below) the bottom of the window.
|
This is now staged on https://behat--196.org.readthedocs.build/en/196/guides.html (note that the links in the header are currently broken, but other links should all work as expected). @carlos-granados and anyone else, any thoughts at this early stage are extremely welcome! I'm not primarily/really a frontend designer, and I've tried not to spend too much time on this so far, but wanted to check if people think this is a good direction of travel. |
|
Thanks @acoulton this is looking great. And you seem to have addressed most of my concerns in your comments.
Only thing I would add is that in the old version the ads were more out of the way (on one side of the page instead of at the bottom of page content), not sure how you configure that So, I think you are in a good direction, keep up the good work |
|
@carlos-granados great, thanks for the review. Good point on the ads, I'm sure there must be a way to configure that, I'll see if I can work out what it is! I've not touched dark mode colours at all, and you're correct the code samples (and some other things) don't work there yet. |
Ideally, I would also slightly reduce the whitespace between the main navbar and the page content - however this is tricky to do here as there are no easy / robust CSS selectors we can use. I think this is an improvement as-is, and better to tackle further with a theme contribution.
They need to be relative to the html base url, which varies on ReadTheDocs. Handily, RTD exposes an environment variable that we've already captured to `html_baseurl`
|
@carlos-granados I have done a bit more on this.
|
I think it is looking great and the landing page looks great as well, keep up the good work |
With some python hackery to make it work. There are potentially ways to make the `button` directive able to find document cross-references (rather than hardcoded links). AI suggested a couple, but these didn't seem to actually work - the solutions had hallucinated methods that are not present in sphinx and don't seem to have ever existed.
Currently, we have `/guides` which is not in the TOC but has useful content, and `/user_guide` which is a page with just a raw TOC tree. This pushes things down a level in the TOC and is why we've needed a separate "guides" link to get back to the page with the actual content as this does not appear in the TOC at all. It also meant the "next" link flow between quick start, guides and the user guide was not in a logical sequence. Instead, reorganise the TOC structure slightly so that: * The index is now our main document, so the TOC in the sidebar works as expected. The index then automatically renders the quick start as the "next" link, and the quick start takes you to documentation. * We remove the old "/user_guide" page which only had the autogenerated TOC, instead putting a TOC at the bottom of the documentation page. We can add a redirect in RTD for the old `/user_guide.html` URL. * We therefore don't need the hardcoded "Guides" or "Community" links in the top nav, as these replicate the (more logically sequenced) links in the main nav.
If we're only linking to a Github search, I'm not sure this merits a top navigation link. It feels closer to the unofficial / useful content links in "Useful Resources" at the moment. If in future we wanted to list extensions, we could add a separate page in this section of the docs.
Although surely it's possible to have the same sub-heading on different pages without Sphinx reporting an error?
The WIP custom CSS file was already getting hard to keep tidy, and some of the styles (particularly wagtail fixes) need more inline documentation as to what they are which we don't really want in the end-user output. lightningcss is a tiny dependency-free CSS bundler and minifier which we can install with python (they provide binary packages but distribute them through npm which we don't have). This allows us to break up the CSS, add more comments, and also use some more modern CSS (e.g. nested selectors) and have it transpiled if required. Also migrated our colour scheme styles to use CSS variables rather than applying directly, this will make it much easier to provide a full set of variables for dark mode.
Improves the readability considerably and largely solves the colour contrast issue.
Broadly following the current Behat documentation site.
A more organic green rather than the quite-primary I started with.
Mostly because it was sitting very bright at the bottom of a dark mode page.
We are using the RTD search, so this is not required and is linking to an index that does not have useful content.
Better positioning on mobile.
|
@carlos-granados I've done some more on this, I think it's getting pretty close. Feedback very welcome! https://behat--196.org.readthedocs.build/en/196/user_guide/initialize.html |
|
@acoulton I think this is looking quite good, I could not find anything that looked weird or needing improvement |
|
@carlos-granados great! There are a couple of bits of actual content that I've spotted while looking around, and I still want to explore contributing back some of these things to Wagtail if they'll accept them. But I also think it's quite good (and a good step forward on status quo), and definitely a big enough diff already in this PR. So if you're happy to approve, maybe we merge and ship it and then we can address anything else in subsequent PRs? |
This is an early work-in-progress for replacing the current custom theme with a modern alternative.
I've had a good look through https://sphinx-themes.org/, and IMO the Wagtail theme is the best for us considering design / flexibility / how recently maintained & supported it is etc. It has a responsive layout that makes good use of larger screens, built in "dark mode" support, "Edit on Github" links on docs pages, and a "copy to clipboard" on code snippets amongst other useful features.
There are a few things about the Wagtail theme that don't suit us perfectly. So far I think we'll be able to work around all of them. In some cases I might be able to contribute new config options / extension points back to the Wagtail theme which would make that neater, but sphinx also allows us to copy & modify individual theme files if required.
The current Behat site is essentially greyscale with a background texture. IMO this looks quite dated. The Wagtail (and most other modern) themes works best with some sort of colour scheme. I think we should be "green-but-not-the-same-green-as-official-cucumber" because a) cucumbers are green and b) a passing suite is green. I spent about 30 seconds googling "cucumber colour palette" and picked a palette for the WIP - this can obviously be changed.
Known issues / work-in-progress:
behattext logo as on the current site. However I notice that saysbehatwhen everywhere else we useBehat.Comfortaaheading font)Fixes #181