Update doc-build tools to support new ``pydata-sphinx-theme`` & switch from obsolete ``sphinx-panels``

[JoelPasvolsky]

I'll open this WIP now but will continue after my PTO. I've fixed the worst of the backwards incompatibilities but still need to

• :white_check_mark: Fix the rst_prolog = f" .. |python_requires| replace:: {setup_cfg['options']['python_requires']}", which is currently commented out (it otherwise adds a blank line at the top of every page). Fixed this here
• :white_check_mark: get the badges to float right on the index page (I think the class's use of ::before makes the float not work). Made a workaround after chat with @randomir
• :white_check_mark: docs/_static/theme_overrides.css can definitely be shortened, I just duplicated for now. Fixed.
• :white_check_mark: clean up a bit from my testing and old stuff. Done

Notice that the theme now supports dark mode. A future PR can set a different color scheme more suitable for dark mode. I can also turn off the mode's availability until then.

[JoelPasvolsky]

Looks like I might need to also either update CircleCI to use a new Python version to run doc builds or use an earlier version of Sphinx

[arcondello]

It's configured here: https://github.com/dwavesystems/dwave-ocean-sdk/blob/180ec75f6fcda0d7515f8977d8b07eb9e1406afb/.circleci/config.yml#L134

What does RTD currently use?

[arcondello]

Looks like it used 3.8 by default, but it is configurable.

[JoelPasvolsky]

Looks like it used 3.8 by default, but it is configurable.

Yes, I actually recently made a PR to move to this configuration

[arcondello]

Then yes! We can use whatever version you need :laughing:

[arcondello]

So most of this is bike shedding but...

For comparison two images (found here)

New Docs

Old Docs

Comments

1) I don't love that the links are underlined. E.g. 2) I prefer the old pink inline code to the orange 3) I don't love the new python syntax coloring 4) The code link is using green rather than blue E.g. 5) This isn't int he example image, but the bar at the top has weird coloring when I mouse over. E.g.

[JoelPasvolsky]

1. I don't love that the links are underlined. E.g.

It's simple to remove the link underlining (a {text-decoration: none;} as a theme override) but I believe they added the underline to help people with visual impairments recognize hyperlinks so I propose to keep that.

2. I prefer the old pink inline code to the orange

I restored the previous color (--inline-code-pink: rgb(232, 62, 140);) based on the original pydata_sphinx_theme==0.8.0 code. Again, I believe the added backgrounding is to help with visual impairments, so I left that.

3. I don't love the new python syntax coloring

Apparently they are using GitHub code block style now. I don't think we want to try restyling that ourselves

4. The code link is using green rather than blue E.g.

Ha, I figured out how to fix that to my huge surprise: --pst-color-inline-code-links: var(--dwave-color-ocean-blue);

5. This isn't int he example image, but the bar at the top has weird coloring when I mouse over. E.g.

I don't know how to change that one :shrug:

[arcondello]

All makes sense to me, thanks

[JoelPasvolsky]

@randomir & @arcondello, see this rendering and let me know if I should go ahead and merge this commit into my branch. (After editing it, of course.)

[arcondello]

I personally prefer it, though I would take a 2x3 or 3x3 subset of the packages to highlight.

[JoelPasvolsky]

I personally prefer it, though I would take a 2x3 or 3x3 subset of the packages to highlight.

It's nicely flexible, we could build off something like this:

[JoelPasvolsky]

I personally prefer it, though I would take a 2x3 or 3x3 subset of the packages to highlight.

Another option to consider is the use of tabs for (default) clean look and (alternative tab) full list of packages:

[arcondello]

Another option to consider is the use of tabs for (default) clean look and (alternative tab) full list of packages

I'd even say the first tab could be boxes and the second tab a list.

[JoelPasvolsky]

The updated docset can be seen here