sphinx-tabs

Create tabbed content in Sphinx documentation when building HTML.

For example, see the [Raw] code of docs/index.rst which generates the following:

A live demo can be found here: https://sphinx-tabs.readthedocs.io

Installation

pip install sphinx-tabs

To enable the extension in Sphinx, add the following to your conf.py:

extensions = ['sphinx_tabs.tabs']

If needed, there is a configuration option to allow additional builders to be considered compatible. For example, to add the

linkcheck

sphinx_tabs_valid_builders = ['linkcheck']

If you are using Read The Docs for building your documentation, the extension must be added as a requirement. Please add the following to

requirements.txt

sphinx-tabs

Contributing

We welcome all contributions! See the EBP Contributing Guide for general details.

The simplest way to run tests is to install pre-commit for linting and tox for unit tests and documentation build:

$ pre-commit run --all

$ tox -p

Basic Tabs

Basic tabs can be coded as follows:

.. tabs::

   .. tab:: Apples
  Apples are green, or sometimes red.
   .. tab:: Pears
  Pears are green.
   .. tab:: Oranges
  Oranges are orange.

The contents of each tab can be displayed by clicking on the tab that you wish to show. Clicking on the tab that is currently open will hide the tab's content, leaving only the tab set labels visible.

Alternatively, tab sets can be focused using :kbd:

Tab

Left Arrow

Right Arrow

Enter

Grouped Tabs

Tabs can be grouped, so that changing the current tab in one tabset changes the current tab in all other tabsets containing a tab with a matching label. For example:

.. tabs::

   .. group-tab:: Linux
  Linux Line 1
   .. group-tab:: Mac OSX
  Mac OSX Line 1
   .. group-tab:: Windows
  Windows Line 1
.. tabs::
   .. group-tab:: Linux
  Linux Line 1
   .. group-tab:: Mac OSX
  Mac OSX Line 1
   .. group-tab:: Windows
  Windows Line 1

If permitted by the user's browser, the last selected group tab will be remembered when changing page. As such, if any tabsets on the next page contain a tab with the same label it will be selected.

Code Tabs

Grouped tabs containing code with syntax highlighting can be created as follows:

.. tabs::

   .. code-tab:: c
     int main(const int argc, const char **argv) {
       return 0;
     }
   .. code-tab:: c++
     int main(const int argc, const char **argv) {
       return 0;
     }
   .. code-tab:: py
     def main():
         return
   .. code-tab:: java
     class Main {
         public static void main(String[] args) {
         }
     }
   .. code-tab:: julia
     function main()
     end
   .. code-tab:: fortran
     PROGRAM main
     END PROGRAM main

Code tabs also support custom lexers (added via sphinx

conf.py

code-tab

By default, code tabs are labelled with the language name, though a custom label can be provided as an optional second argument to the

code-tabs

.. tabs::

   .. code-tab:: c I love C
     int main(const int argc, const char **argv) {
       return 0;
     }
   .. code-tab:: py I love Python more
     def main():
         return

The tab label is used to group tabs, including

code-tabs