Relevant To¶
The 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 lsp_getting_started guide for an example of this extension in action.
Note
This extension currently only supports HTML builders.
Getting Started¶
The 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 conf.py
:
extensions = [
"esbonio.relevant_to"
]
Then within your documentation, “relevant sections” are defined using the relevant-to
directive.
- .. 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 (
Red
,Green
orBlue
in 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
However section titles are not supported.