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 or Blue in this case) and the definition is the term’s corresponding content.

Here is how the above example is rendered.

Colour:

The body of a definition can contain most reStructuredText constructs including roles and directives

However section titles are not supported.