Tabbed views for Sphinx

3.5.0 · active · verified Sat Apr 11

Sphinx Tabs is a Sphinx extension that provides directives for creating tabbed content in Sphinx documentation when building HTML. It is actively maintained, with version 3.5.0 currently available, and releases frequently address compatibility with new Sphinx and Docutils versions.

Warnings

breaking sphinx-tabs v3.5.0 (and newer versions) officially dropped support for Sphinx versions older than 7. Ensure your Sphinx installation is version 7 or higher when upgrading sphinx-tabs to 3.5.0+.
Fix: Upgrade your Sphinx version to 7 or newer (`pip install 'sphinx>=7'`) or pin sphinx-tabs to an older compatible version (`pip install 'sphinx-tabs<3.5.0'`).
gotcha The `.. include::` directive does not function correctly when placed inside a `.. code-tab::` directive. For including general reStructuredText content within tabs, use `.. tab::` or `.. group-tab::` instead.
Fix: Refactor your reStructuredText to use `.. tab::` or `.. group-tab::` for content that needs to include other files, or manually embed the content directly.
gotcha When using 'grouped tabs' by providing a group name to the `.. tabs::` directive (e.g., `.. tabs:: my-group`), ensure that the tab labels you intend to synchronize are consistent across all tab sets within that group on the same page. Inconsistent labels may lead to unexpected synchronization behavior.
Fix: Standardize tab labels across all `.. tabs::` blocks that share the same group name to ensure proper synchronization.
gotcha If you are building your documentation on Read The Docs, you must explicitly add `sphinx-tabs` to your `requirements.txt` file in your project's root or docs folder, in addition to installing it in your local environment, for the extension to be recognized during the build process.
Fix: Add `sphinx-tabs` to your `requirements.txt` file (e.g., `sphinx-tabs==3.5.0`) to ensure it's installed on Read The Docs.
gotcha Some users have reported compatibility issues with `sphinx-tabs` and certain Sphinx themes (e.g., `pydata-sphinx-theme`), where the presence of `sphinx-tabs` can interfere with theme-specific features like version switchers, even if tabs are not actively used on the page.
Fix: If experiencing conflicts, check the issue trackers of both `sphinx-tabs` and your chosen Sphinx theme for known incompatibilities and potential workarounds or updates. You might need to adjust CSS or JavaScript, or consider alternative tab extensions if no fix is available.

Install

pip install sphinx-tabs Install latest version

Imports

sphinx_tabs.tabs
```
extensions = ['sphinx_tabs.tabs']
```
Add 'sphinx_tabs.tabs' to the 'extensions' list in your conf.py to enable the extension.

Quickstart

This quickstart guides you through setting up a basic Sphinx project, enabling the `sphinx-tabs` extension, and creating an example reStructuredText file with a tabbed interface. After building, you can view the tabbed content in the generated HTML documentation.

mkdir myproject
cd myproject
mkdir docs
cd docs
sphinx-quickstart  # Follow prompts, say 'y' to Separate source and build dirs
# In docs/conf.py:
# extensions = [
#     'sphinx.ext.autodoc',
#     'sphinx.ext.napoleon',
#     'sphinx_tabs.tabs',
# ]
# html_theme = 'alabaster' # Or any other Sphinx theme

# In docs/index.rst:
# .. _index:
#
# Welcome to My Sphinx Tabs Project's documentation!
# ==================================================
#
# .. tabs::
#
#     .. tab:: Python
#
#         .. code-block:: python
#
#             def hello_world():
#                 print("Hello, Python!")
#
#     .. tab:: Shell
#
#         .. code-block:: bash
#
#             echo "Hello, Shell!"
#
#     .. tab:: Markup
#
#         Hello from **reStructuredText**!
#
# This project demonstrates `sphinx-tabs` functionality.
#
# Indices and tables
# ==================
#
# * :ref:`genindex`
# * :ref:`modindex`
# * :ref:`search`

# Then build:
# make html
# Open _build/html/index.html

view raw JSON →