esbonio.relevant_to extension is similar to the sphinx-panels and sphinx-tabs extensions, where you can define sections of documentation that is only relevant to a given subject (e.g. Python version) and be able to choose between them.
However, instead of presenting these sections as tabs, this extension uses a dropdown which scales better when you have a large collection of subjects to cover (like text editors!)
Additionally this extension
Reflects the chosen topic in the page’s URL, making subject choices linkable
Uses htmx to swap out the relevant sections.
See the Esbonio language server’s Getting Started guide for an example of this extension in action.
This extension currently only supports HTML builders.
esbonio.relevant_to is available through the
esbonio-extensions Python package.
$ pip install esbonio-extensions
Ensure that the extension is enabled by including
esbonio.relevant_to in the
extensions list inside your project’s
extensions = [ "esbonio.relevant_to" ]
Then within your documentation, “relevant sections” are defined using the
- .. relevant-to::#
Define sections that can be swapped out based on the chosen subject. Consider the following example.
.. relevant-to:: Colour Blue The chosen colour is blue. Green The chosen colour is green. Red The chosen colour is red.
The argument to the directive defines the category of subject this section is about. The content of the directive must be a valid definition list where the term is the name of the subject (
Bluein this case) and the definition is the term’s corresponding content.
Here is how the above example is rendered.
The body of a definition can contain most reStructuredText constructs including roles and directives
.. relevant-to:: Editor VSCode (Esbonio) .. figure:: /images/vscode-screenshot.png :align: center :target: /_images/vscode-screenshot.png The Esbonio VSCode extension.
However section titles are not supported.