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

[Proof of concept] Customize Furo to use Qiskit branding #233

Closed
wants to merge 1 commit into from

Conversation

Eric-Arellano
Copy link
Collaborator

@Eric-Arellano Eric-Arellano commented Mar 27, 2023

Seeing if we can satisfy #232 by using Furo's builtin customization rather than vendoring the theme and modifying the original source code. That will likely be much easier for us to maintain. For example, no need to have infrastructure that uses Node.js to compile the Sass files.

We will need to solve pradyunsg/furo#204 still because we can't expect everyone to put this code in their conf.py and templates folder. We need to pre-set this all and distribute it as our own custom theme.

Customization requirements

Color scheme

We can customize any of Furo's Sass variables via html_theme_options. See https://github.com/pradyunsg/furo/blob/main/src/furo/assets/styles/variables/_colors.scss. For example, we set the color here to Qiskit purple:

Screenshot 2023-03-29 at 11 16 54 AM

We can also set whatever CSS rules we want in custom.css.

TODO:

  • Figure out what color variables we want to change
  • Decide color scheme for dark mode

Fonts

This is set via html_theme_options, for both the normal font and monospace font. We load the font via Google Fonts loaded in the header.

Screenshot 2023-03-29 at 11 17 30 AM

Top nav bar

We extend base.html to load our web components, then change page.html to render the nav bar at the top of the page.

Screenshot 2023-03-29 at 11 18 04 AM

--

Screenshot 2023-03-27 at 3 32 09 PM

TODO:

  • Fix the margin so it doesn't hide Furo's own top nav bar.
  • On mobile, don't render the docs title and version.

Footer & analysis code

We extend base.html to add our analytics code, then change the footer page.html to include our "Was this page helpful?" question. We use Furo's next page and copyright code, but could use our own if we wanted.

Screenshot 2023-04-04 at 10 54 26 AM

TODO:

  • Why won't the footer <hr> render? It's in the DOM.

Side bar: languages and versions

This works by adding custom side bar elements, set in conf.py. While it does not yet have any styling, we can add that in a follow up. The basic proof of concept works and e.g. clicking on the elements works.

Screenshot 2023-04-10 at 10 02 04 AM

TODO:

  • Add styling to both elements
  • Report and fix Furo bug with search bar being hidden on mobile when sidebar_hide_name=True

Sorry, something went wrong.

Verified

This commit was signed with the committer’s verified signature.
dtolnay David Tolnay
@Eric-Arellano
Copy link
Collaborator Author

Eric-Arellano commented Apr 13, 2023

Closing in favor of #269, which restructures this code so that we can actually safely land the Furo theme.

@Eric-Arellano Eric-Arellano deleted the furo-via-conf-py branch April 13, 2023 14:56
Eric-Arellano added a commit that referenced this pull request Apr 14, 2023

Verified

This commit was signed with the committer’s verified signature.
dtolnay David Tolnay
We plan to land the Furo proof of concept soon
(#233), so that people
can more easily finish Qiskit-ifying the theme.

We have to set slightly different conf.py values, like
`html_theme_options`. We'll do that by something like this:

```python
if "FURO" in os.environ:
   # furo options
else:
   # pytorch options
```

So, this is prework to make `conf.py` as simple as possible before
adding new complexity.

--

This also removes the unnecessary `.. contents::` directives from some
pages. They didn't actually do anything, but cause a huge warning when
using Furo. With Pytorch, we still have our right page-level table of
contents even without it.
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.

None yet

1 participant