Is there a way to define a "base theme"?

[astrojuanlu]

In kedro-org/kedro#3016 we're thinking of creating a Sphinx theme that derives from sphinx-rtd-theme (although the base could change, which one we pick is not important) that contains our own assets and can be easily used in other project.

Does sphinx-theme-builder help in creating a Sphinx theme that has another one as "base"? Or would we have to essentially fork or copy-paste the files of the base theme to our own repo and then tweak them?

[pradyunsg]

Hi there! This is certainly doable.

https://github.com/executablebooks/sphinx-book-theme/blob/master/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf#L2 is the information that Sphinx's templating engine AKA theme system needs to have.

Other than that, add a runtime dependency on it via project.dependencies and you should be good.

The derived theme can override specific templates as well as do a bunch of other stuff as it is a full Sphinx extension too. The parent theme is also loaded as an extension, IIRC.

[astrojuanlu]

Thanks a lot!

[webknjaz]

There's a gotcha with Jinja2 templates, though: there are two sources of variables — that theme config file and html context. An unobvious thing is that in jinja2 templates, the former are exposed with the theme_ prefix while the latter are accessible as is.

[pradyunsg]

That's not really a gotcha but it is how Sphinx's theme configuration works with the Jinja variables as documented.

I guess it's subtle and confusing if you haven't seen it before/read the documentation. 🤷🏻

[webknjaz]

Yep, that's what I meant. The end-users may not know where to place data in conf.py (2 places), and the template authors inheriting from other templates may not expect there's two sources of variables in the parent one (or further up the chain).