Allow inheriting from furo

[jezdez]

When I tried to create an own theme based on furo I stumbled over the fact that the context variables are only initialized if the theme is called "furo":

furo/src/furo/__init__.py

Lines 136 to 137 in fd66689

	if app.config.html_theme != "furo":
	return

This led to the follow error:

❯ make html
Running Sphinx v4.1.2
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
Theme error:
An error happened in rendering the page index.
Reason: UndefinedError("'furo_pygments' is undefined")
make: *** [html] Error 2

It would be splendid to be able to inherit from furo for reusing in an own custom theme.

[pradyunsg]

This is tricky. A whole bunch of stuff in Furo's Python side is tied to the exact asset names, or exact contents/structure of the templates.

I'm happy to accept a PR for this, but, TBH, I'm not even sure what exactly the needs of downstream themes would be from this one; or what promises around stability I'd be willing to make.

[kapooramit]

@jezdez : Were you able to find a way of creating a custom theme using furo? If yes - can you share how?

[jezdez]

@kapooramit I wasn't and gave up sadly :( But I may try again in the new year..

[kapooramit]

That hurts! Fine then, unless @pradyunsg says otherwise, I am gonna quit too. I spent too much trying to use Furo as base theme but. Ah!
Thank you @jezdez .

[jezdez]

To clarify, I only gave up on inheriting from furo and instead just used the regular ways to extend the style. Still very happy with furo!

[kapooramit]

I understand. Thanks. It is an awesome theme. My requirement is to create a theme for my organization for multiple projects. And then, it will be used to deliver customer docs as well. So branding and name is important. CSS and JS alone can do a lot but the name would be required to be changed.

[Eric-Arellano]

I'm happy to accept a PR for this

Hey @pradyunsg, would you still accept a PR for this?

We're hoping to migrate the Sphinx theme for Qiskit—IBM's open source quantum computing library—from a Pytorch fork to Furo. Because we have multiple repos, we release a package qiskit_sphinx_theme to PyPI with the theme. It would not be sustainable for us to have each Qiskit repository override HTML templates & CSS styling in their repo directly.

I'm happy to champion this project. I work on Qiskit for my day job, with documentation as my main priority, so I will be around for any maintenance too.

I'm not even sure what exactly the needs of downstream themes would be from this one

For now, the main thing is to not crash when inheriting the theme. That is, this theme.conf should work:

[theme]
inherit = furo

I don't think there's much else Furo will need to do. Sphinx has solid support already for inheriting themes, including:

• overriding HTML templates by simply including a new version of the file
• adding a custom.css file that gets bundled in the new theme and overrides any of the base theme's styling

or what promises around stability I'd be willing to make

I don't think you need to make any guarantees around stability. It's fair to mark this feature unstable. The only stability that would help us at Qiskit is having a test that I would add to ensure you can inherit the Theme without crashing.

(qiskit_sphinx_theme would pin to exact Furo versions. Anytime we upgrade Furo versions, we'd closely check for any relevant changes.)

P.S. Thanks for this theme and your other work in Python!

Update April 13

See #649 and #648.

[pradyunsg]

Actually, I've gone ahead and dropped the checks, since I figured out what was triggering the issues that were being reported -- 48c0bf2.

That essentially removes the barrier to allowing for inheritance. I'll leave the stability documentation as-is stating that relying of Furo's internals is not OK, which does cover this case anyway.

---

FWIW, overriding html_style or style to be something other that furo.css isn't going to work -- you can add additional stuff via https://pradyunsg.me/furo/customisation/injecting/ in themes as well.

[Eric-Arellano]

This worked brilliantly. Thank you!

FWIW, overriding html_style or style to be something other that furo.css isn't going to work -- you can add additional stuff via https://pradyunsg.me/furo/customisation/injecting/ in themes as well.

We still want to use Furo themes, only extend it.

FYI, for others wanting to do this, this is our folder structure:

qiskit_sphinx_theme/furo/base/
├── base.html
├── page.html
├── sidebar
│   ├── languages.html
│   └── version_list.html
├── static
│   └── styles
│       └── qiskit_customization.css
└── theme.conf

theme.conf:

[theme]
inherit = furo

stylesheet = styles/furo.css, styles/furo-extensions.css, styles/qiskit_customization.css

sidebars =
  sidebar/languages.html,
  sidebar/search.html,
  sidebar/scroll-start.html,
  sidebar/navigation.html,
  sidebar/version_list.html,
  sidebar/scroll-end.html

We hardcode some of the Sass variables in qiskit_customization.css like this:

body {
    --color-brand-primary: #8A3FFC;
    --color-brand-content: #8A3FFC;
    --font-stack: 'IBM Plex Sans', 'Roboto', 'Helvetica Neue', 'Arial', sans-serif;
    --font-stack--monospace: 'IBM Plex Mono', 'Consolas', 'Courier New', monospace;
}

We extend HTML templates by copying and pasting Furo's file, then adding our custom code. For example, page.html:

{% extends "base.html" %}

{% block body -%}
{{ super() }}
{% include "partials/icons.html" %}

<!-- QISKIT FURO CHANGE: start. Add our top nav bar. -->
<qiskit-ui-shell variant="hide-account"></qiskit-ui-shell>
<!-- QISKIT FURO CHANGE: end. -->

<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
...

With HTML templates, it did not work to use {% extends '!base.html' %} like normal because it results in infinite recursion.

--

Thanks again! I'll put up a PR adding Qiskit to "Who Uses" once we ship this :)

[pradyunsg]

In 48c0bf2, I've removed the check that enforced that the theme name be furo.

People are welcome to go buckwild with inheriting from this theme; but know that there are no stability promises involved if you do this -- see https://pradyunsg.me/furo/stability/#undocumented-unstable-customisations for the details on that.

Thanks @Eric-Arellano for the nudge on this, since that made me look into this again. :)