Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert HTML to reST with sphinx-design #96

Draft
wants to merge 9 commits into
base: main
Choose a base branch
from

Conversation

QuLogic
Copy link
Member

@QuLogic QuLogic commented Aug 20, 2024

Using sphinx-design's grid, tabs, and cards, we can replicate most of our brochure site using reST instead of HTML. This allows us to drop a lot of custom CSS, some JavaScript, and most importantly, allows wiring up the build for translations.

This is not a perfect translation, perhaps 90% of the way there. Notable differences are:

  1. I didn't keep the tweak to the document the full width with smaller max-width containers. That makes us use the default, which is a bit narrower, but probably not enough to matter. The other major difference is that the coloured rules are only the width of the content, instead of the full page. I don't think that there's any way to make them overflow easily.
  2. The containers in sphinx-design cannot have any reST headings, so the HTML doesn't have headings, only div that are styled like them; this is a bit annoying from a semantic point of view, and possibly broken for accessibility. I'm not sure if this is something sphinx-design can fix or if it's inherent to reST.
  3. While I was mostly able to replicate the gradient on the tab colours, I wasn't able to replicate the tab labels being on the side. I'm not too sure if this is possible in pure CSS with the HTML structure that sphinx-design generates, but maybe it's something that could be implemented on their side.
  4. The footer remains specified in HTML, but I wonder if we want to tweak its style a bit since it remains full-width while everything else isn't (including the header, which comes from pydata-sphinx-theme).

Along those lines, I had some ideas of possible tweaks:

  1. News items could be placed in cards for a slightly different styling. The cards could be fully clickable as well, though that would preclude internal links like the one that is in the GSoC news entry.
  2. Instead of tabs, the tool examples could be a card carousel

This isn't needed for the remaining ones, but may be useful in the
future.
Namely, ensure that they switch to a single column when on narrower
displays, and remove extra margins on quick links.

Also, switch quick link container to a flexbox instead of grid, so that
everything is aligned in the center correctly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant