tessl/pypi-sphinx-tabs

Sphinx extension for creating tabbed views in HTML documentation with syntax highlighting and synchronization.

Overview

Eval results

Files

Tab Directives

Name: tessl/pypi-sphinx-tabs
Author: tessl

RST directives for creating different types of tabbed content in Sphinx documentation. All directives generate accessible HTML with ARIA attributes and support keyboard navigation.

Capabilities

Main Container Directive

Creates the top-level container for a set of tabs.

class TabsDirective(SphinxDirective):
    """Top-level tabs directive"""
    has_content = True
    
    def run(self):
        """Parse a tabs directive and return container nodes"""
        # Returns: List[nodes.container]

Usage:

.. tabs::

   .. tab:: First Tab
   
      Content of first tab
      
   .. tab:: Second Tab
   
      Content of second tab

Individual Tab Directive

Creates individual tabs within a tabs container.

class TabDirective(SphinxDirective):
    """Tab directive for adding a tab to a collection"""
    has_content = True
    
    def run(self):
        """Parse a tab directive and return panel node"""
        # Returns: List[SphinxTabsPanel]

Usage:

.. tab:: Tab Title

   Any valid reStructuredText content can go here:
   
   - Lists
   - Code blocks
   - Images
   - Other directives

Parameters:

First line becomes the tab title
Remaining content becomes tab body
Supports all standard RST content

Group Tab Directive

Creates tabs that synchronize across multiple tab sets on the same page.

class GroupTabDirective(TabDirective):
    """Tab directive that toggles with same tab names across page"""
    has_content = True
    
    def run(self):
        """Parse a group-tab directive with synchronization"""
        # Returns: List[SphinxTabsPanel] with group-tab class

Usage:

.. tabs::

   .. group-tab:: Linux
   
      Linux-specific instructions
      
   .. group-tab:: Windows
   
      Windows-specific instructions

.. tabs::

   .. group-tab:: Linux
   
      More Linux content (will sync with above)
      
   .. group-tab:: Windows
   
      More Windows content (will sync with above)

Features:

Tabs with matching labels synchronize across tab sets
Selection persists across page navigation (browser permitting)
Base64 encoding used for internal tab IDs

Code Tab Directive

Creates tabs with syntax-highlighted code blocks.

class CodeTabDirective(GroupTabDirective):
    """Tab directive with a codeblock as its content"""
    has_content = True
    required_arguments = 1      # Lexer name
    optional_arguments = 1      # Custom label
    final_argument_whitespace = True
    
    # Inherits all CodeBlock options
    option_spec = {
        "force": directives.flag,
        "linenos": directives.flag,
        "dedent": int,
        "lineno-start": int,
        "emphasize-lines": directives.unchanged_required,
        "caption": directives.unchanged_required,
        "class": directives.class_option,
        "name": directives.unchanged,
    }
    
    def run(self):
        """Parse a code-tab directive with syntax highlighting"""
        # Returns: List[SphinxTabsPanel] with code content

Usage:

.. tabs::

   .. code-tab:: python

      def hello():
          print("Hello World!")

   .. code-tab:: javascript

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

   .. code-tab:: python Custom Label

      # Tab will show "Custom Label" instead of "Python"
      print("Custom labeled tab")

Arguments:

Required: Lexer name (e.g., python, javascript, c++)
Optional: Custom tab label (overrides language name)

Options:

All Sphinx CodeBlock options supported:
- :linenos: - Show line numbers
- :emphasize-lines: 1,3-5 - Highlight specific lines
- :caption: Code Example - Add caption
- :dedent: 4 - Remove indentation
- :lineno-start: 10 - Start line numbering at 10

Lexer Resolution:

# Internal lexer mapping
LEXER_MAP = {}  # Maps short names to full lexer names
# Populated from pygments.lexers.get_all_lexers()

Error Handling:

Raises ValueError for unrecognized lexers
Supports custom lexers added via Sphinx configuration
Falls back to lexer name resolution through pygments

HTML Output Structure

All directives generate the following HTML structure:

<div class="sphinx-tabs">
  <div role="tablist" aria-label="Tabbed content">
    <button role="tab" id="tab-0-label" aria-selected="true" aria-controls="panel-0-label">
      Tab Label
    </button>
  </div>
  <div role="tabpanel" id="panel-0-label" aria-labelledby="tab-0-label">
    Tab content here
  </div>
</div>