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.

Sign up for GitHub

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

Jump to bottom

[Epic] Switch to Furo Sphinx theme #232

Closed
Eric-Arellano opened this issue Mar 27, 2023 · 2 comments
Closed

[Epic] Switch to Furo Sphinx theme #232

Eric-Arellano opened this issue Mar 27, 2023 · 2 comments
Milestone
Furo 1.0

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented Mar 27, 2023 •
edited
Loading

Background

Moving away from Pytorch

There are two categories of problems with our current Sphinx theme, a fork of Pytorch:

User limitations

  1. Poor mobile support
  2. Looks a little dated
  3. Not fully compliant with accessibility
  4. No dark mode

Developer frustrations

  1. 12k line CSS file with
    1. lots of conflicting rules (aka “specificity wars”)
    2. “pytorch” references everywhere
  2. Porting fixes from pytorch is getting harder, given that the CSS was not maintainable to begin with and we’ve made enough changes

Rather than trying to salvage the current theme, we are recommending using a new, more modern theme from https://sphinx-themes.org/. The newer ones are built to follow best practices like use Sass and have excellent mobile support.

Furo

We are recommending using Furo: https://sphinx-themes.org/sample-sites/furo/. It was built in 2020 for the new pip docs and is used by Black, urllib3, attrs, and the Python developer guide.

It meets all of our criteria, including looking modern, having great mobile support, being extensible to Qiskit's top-nav bar, and having maintainable Sass-based CSS.

We also strongly considered Book: https://sphinx-themes.org/sample-sites/sphinx-book-theme/. But it's top-nav bar would be much harder to get working with the Qiskit one, and we also believe it's not as nice-looking.
This was referenced Mar 27, 2023
Closed
Closed
@Eric-Arellano Eric-Arellano mentioned this issue Apr 13, 2023
Merged
@Eric-Arellano Eric-Arellano changed the title [WIP issue description] Qiskit-ify the Furo Sphinx theme [Epic] Finish Qiskit-ifying the Furo Sphinx theme Apr 13, 2023
@Eric-Arellano Eric-Arellano changed the title [Epic] Finish Qiskit-ifying the Furo Sphinx theme [Epic] Switch to Furo Sphinx theme May 3, 2023
@Eric-Arellano Eric-Arellano added this to the Furo milestone May 3, 2023
Eric-Arellano added a commit that referenced this issue May 3, 2023
@Eric-Arellano
Add experimental _qiskit_furo theme (#269)
4ca7eb3 
This PR adds a private `_qiskit_furo` theme to `qiskit_sphinx_theme`,
using Sphinx's inheritance mechanism. That allows us to build
`example_docs` with Furo by using `THEME=_qiskit_furo tox -e py`.

The Furo theme still has some CSS issues, documented in
#232. But I'd like
to land this theme and make those improvements in followup PRs. That
will make it easier for people (like Digital) to collaborate on
improving this theme, and it will make reviews more focused on the
specific CSS fix.

> using Sphinx's inheritance mechanism

This is much more maintainable than vendoring all the Furo code in our
repository.

For HTML template overrides, we add the comments `<!-- QISKIT CHANGE:
start. ... -->` and `<!-- QISKIT CHANGE: end. -->` to make clear our
changes. We also put substantial changes in dedicated HTML Jinja
template files, then use `{% include "..." %}`. That will make it easier
to sync with upstream Furo.

## Web components

We duplicate the same top-nav-bar.js file for both Pytorch and Furo.
This is because Sphinx requires the file to be in the `static/` folder
for both themes. We can't put it in a common folder. Using symlinks to
copy the file in didn't work either due to Python packaging.

We use a Jest test to ensure that the two files are in sync.
@coruscating
Copy link
Collaborator

I tried building the Qiskit-Experiments docs with the current Furo theme (as of 97f2029) and here are some points I noted so far:

  • I thought setting _THEME=_qiskit_furo in the tox build environment would be enough, but I had to set html_theme = "_qiskit_furo" in conf.py to get it to work since it was hardcoded to qiskit_sphinx_theme before. This is mostly a note for anyone else trying to test the theme on an existing project.
  • Building pages are quite a bit slower than with the previous theme, which is a problem. I'm not sure whether this is an Experiments-specific problem (the build on the example docs in this repo is very fast) and whether there's a way to speed things up.
  • I like that the destinations of links are highlighted now!
  • The scrolling animation when clicking on a sidebar link takes a while to get to the destination when the page is long. Maybe we can get rid of the animation?

@Eric-Arellano Eric-Arellano mentioned this issue May 8, 2023
Closed
@Eric-Arellano Eric-Arellano mentioned this issue Jun 28, 2023
Merged
Eric-Arellano added a commit that referenced this issue Jun 30, 2023
@Eric-Arellano
Add qiskit theme based on Furo (#425)
34fe6c9 
Unblocks #232. With
this PR, users will be able to set `html_theme = "qiskit"` to use Furo.

This PR adds instructions about how to migrate.

It also switches the default theme in `qiskit_sphinx_theme`'s example
docs to `qiskit`. 95% of my work this month has been on Furo, so that's
a better default.

## Reminder: `qiskit_ecosystem` theme upcoming

Once we add the Ecosystem theme, only Qiskit itself should use the
`qiskit` theme. In the meantime, everyone should migrate from
`qiskit_sphinx_theme` to `qiskit` (barring migration issues).
@Eric-Arellano
Copy link
Collaborator Author

Qiskit has been using Furo for a few weeks now 🎉 https://qiskit.org/documentation/

This was referenced Sep 25, 2023
Merged
Merged
Merged
Merged
Closed
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
@arnaucasau arnaucasau mentioned this issue Oct 18, 2023
Merged
@arnaucasau arnaucasau mentioned this issue Oct 18, 2023
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
No open projects
Qiskit Sphinx Theme
Status: Done
Milestone
Furo 1.0
Development

No branches or pull requests
2 participants
@coruscating @Eric-Arellano