# sphinx_code_tabs

This is a Sphinx extension that adds a `tabs` directive for creating a tabbed widget, allowing the user to switch between them. The individual tabs can be code blocks or general content.

This can be used to e.g. show a snippet in multiple languages, display instructions for alternative platforms, or switch between code and output.

# Installation

    pip install sphinx_code_tabs

To enable the extension in sphinx, simply add the package name in your `conf.py` to the list of `extensions`:

    extensions = [
        ...
        'sphinx_code_tabs',
    ]

# Usage

By enabling the extension you get access to the `tabs` directive that declares a notebook of alternative tabs which looks as follows:

- bash
- C/C++
- python
- Output

    echo "Hello, *World*!"

    #include <stdio.h>
    int main() { printf("Hello, *World*!\n"); }

    print("Hello, *World*!")

Hello, World!

The individual tabs are created with the `tab` or `code-tab` directives. A `tab` can contain arbitrary restructuredText, while a `code-tab` acts like a `code-block` and accepts all corresponding arguments. Both types of tabs can appear in the same notebook.

The `:selected:` option allows to switch to a specified tab at start. By default, the first tab is used.

For example, this is the source of above example:

    .. tabs::

        .. code-tab:: bash

            echo "Hello, *World*!"

        .. code-tab:: c
            :caption: C/C++
            :emphasize-lines: 2

            #include <stdio.h>
            int main() { printf("Hello, *World*!\n"); }

        .. code-tab:: python

            print("Hello, *World*!")

        .. tab:: Output
            :selected:

            Hello, *World*!

## Grouped tabs

The `tabs` directive takes an optional argument that identifies its tab group. Within a given tab group, all notebooks will automatically be switched to the same tab number if the tab is switched in one member of the group. It is your responsibility to make sure that each member of the group has the same number and ordering of tabs. Example:

- bash
- python

    echo "Hello, group!"

    print("Hello, group!")

- bash
- python

    echo "Goodbye, group!"

    print("Goodbye, group!")

Source:

    .. tabs:: lang

        .. code-tab:: bash

            echo "Hello, group!"

        .. code-tab:: python

            print("Hello, group!")

    .. tabs:: lang

        .. code-tab:: bash

            echo "Goodbye, group!"

        .. code-tab:: python

            print("Goodbye, group!")

# Project links

- |Version|

- |License|

- |Documentation|