search

pradyunsg / furo

A clean customizable documentation theme for Sphinx
https://pradyunsg.me/furo/quickstart
MIT License
2.65k stars 304 forks source link

Add `nox -s inherited-theme` to check theme inheritance works #648

Closed Eric-Arellano closed 1 year ago

Eric-Arellano commented 1 year ago

This PR adds a bare-bones test_theme_inheritance project that uses Sphinx's theme inheritance. This allows us to verify that theme inheritance continues to work. (See https://github.com/pradyunsg/furo/discussions/204 for that feature request.)

No stability guarantees

Furo makes zero guarantees about the stability of inheriting it as a theme. For example, the helper functions _html_page_context and _builder_inited will stay private and may change at any time.

The only guarantee—tested by this PR—is that it will be possible to inherit Furo. But how you do that may change.

Projects inheriting this theme are expected to pin to an exact Furo version, and closely check for changes when upgrading to a new version.

Eric-Arellano commented 1 year ago

Qiskit is planning to use theme inheritance with https://github.com/Qiskit/qiskit_sphinx_theme/pull/269. I'll submit PRs to fix any future regressions to theme inheritance we notice when upgrading Furo.

So, this PR is less necessary and has the downside of additional complexity to Furo's repo.

Thanks again for your help with this topic!

pradyunsg commented 1 year ago

I'll add an equivalent to this at some point; once I find enough time to setup testing for this. Thanks for this PR! ^.^