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 builder, add the following to your conf.py:

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 at the root of the project:

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.

Grouped Tabs

Tabs can be grouped, so that changing the current tab in one area changes the current tab in the another area. 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

Code Tabs

Grouped tabs containing code areas 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).

By default, code tabs are labelled with the language name, though can be provided with custom labels like so:

.. 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