Sphinx Tabs

A Sphinx extension that enables developers to create tabbed content in HTML documentation. Sphinx Tabs provides multiple tab types including basic tabs, synchronized group tabs, and code tabs with syntax highlighting. The extension supports keyboard navigation, remembers tab selections across pages, and provides configuration options for various Sphinx builders.

Package Information

• Package Name: sphinx-tabs
• Package Type: pypi
• Language: Python
• Installation: pip install sphinx-tabs

Core Imports

Add the extension to your Sphinx configuration:

# conf.py
extensions = ['sphinx_tabs.tabs']

Basic Usage

# conf.py - Basic setup
extensions = ['sphinx_tabs.tabs']

# Optional configuration
sphinx_tabs_valid_builders = ['linkcheck']  # Additional compatible builders
sphinx_tabs_disable_css_loading = False     # Use custom CSS
sphinx_tabs_disable_tab_closing = False     # Disable tab closing

Basic tabs in reStructuredText:

.. tabs::

   .. tab:: Python

      Python code example:

      .. code-block:: python

         def hello():
             print("Hello from Python!")

   .. tab:: JavaScript

      JavaScript code example:

      .. code-block:: javascript

         function hello() {
             console.log("Hello from JavaScript!");
         }

Architecture

Sphinx Tabs uses a hierarchical structure of custom docutils nodes that render to accessible HTML:

• Container Nodes: SphinxTabsContainer wraps entire tab sets
• Navigation: SphinxTabsTablist contains clickable SphinxTabsTab buttons
• Content: SphinxTabsPanel contains the tab content
• Directives: RST directives (tabs, tab, group-tab, code-tab) generate the node structure
• Assets: Conditional loading of CSS/JS only on pages with tabs

The extension integrates with Sphinx's builder system and supports various output formats while maintaining ARIA accessibility standards.

Capabilities

Tab Directives

Core RST directives for creating different types of tabbed content including basic tabs, synchronized group tabs, and syntax-highlighted code tabs.

# Directive registration in setup()
app.add_directive("tabs", TabsDirective)
app.add_directive("tab", TabDirective) 
app.add_directive("group-tab", GroupTabDirective)
app.add_directive("code-tab", CodeTabDirective)

Tab Directives

Configuration Options

Sphinx configuration values for customizing tab behavior, compatible builders, and asset loading.

# Configuration values
sphinx_tabs_valid_builders = []      # List of additional compatible builders
sphinx_tabs_disable_css_loading = False  # Boolean to disable CSS loading
sphinx_tabs_disable_tab_closing = False  # Boolean to disable tab closing

Configuration

Extension Setup

Main extension setup function and compatibility detection for different Sphinx builders.

def setup(app):
    """Set up the sphinx-tabs extension"""
    # Returns: dict with parallel processing settings

def get_compatible_builders(app):
    """Get list of builders compatible with sphinx-tabs"""
    # Returns: list of builder names

Extension Setup