Sphinx Filter Tabs Extension

A robust Sphinx extension for creating accessible, filterable content tabs using pure CSS and semantic HTML.

📖 View extension and documentation at: https://aputtu.github.io/sphinx-filter-tabs/

This extension provides filter-tabs and tab directives to create user-friendly, switchable content blocks. Perfect for showing code examples in multiple languages, installation instructions for different platforms, or any content that benefits from organized, filterable presentation.

Key Features

• Pure CSS Implementation: Zero JavaScript dependencies for maximum compatibility and performance
• Fully Accessible: WAI-ARIA compliant with native keyboard navigation and screen reader support
• Semantic HTML: Uses standard form controls (radio buttons) for robust, predictable behavior
• Universal Compatibility: Works in all environments where CSS is supported, including strict CSP policies
• Internationalization (i18n): Built-in support for translations, including a complete Danish localization
• Easy Customization: Theme colors and styling through simple CSS custom properties
• Multiple Output Formats: Graceful fallback to sequential content in PDF/LaTeX builds
• 100% Test Coverage: Rigorous verification across all modules, Python versions, and Sphinx releases

Quick Start

Installation

pip install sphinx-filter-tabs

Enable the Extension

Add to your conf.py:

extensions = [
    'filter_tabs',
]

Basic Usage

.. filter-tabs::

    This content appears above all tabs.

    .. tab:: Python

        Install using pip:

        .. code-block:: bash

            pip install my-package

    .. tab:: Conda (default)

        Install using conda:

        .. code-block:: bash

            conda install my-package

    .. tab:: From Source

        Build from source:

        .. code-block:: bash

            git clone https://github.com/user/repo.git
            cd repo
            pip install -e .

Configuration Options

Add these optional settings to your conf.py:

# Use the active Sphinx theme's colors by default, or set an explicit color.
filter_tabs_highlight_color = 'auto'     # Default: 'auto'

# Enable debug logging during development
filter_tabs_debug_mode = False           # Default: False

Advanced Usage

Custom Legend

Override the auto-generated legend:

.. filter-tabs::
   :legend: Select Your Installation Method

   .. tab:: Quick Install
      Content here...

Hide the legend visually while keeping the semantic label for assistive technology:

.. filter-tabs::
   :legend: Select Your Installation Method
   :hide-legend:

   .. tab:: Quick Install
      Content here...

ARIA Labels for Accessibility

Provide descriptive labels for screen readers:

.. filter-tabs::

   .. tab:: CLI
      :aria-label: Command line installation instructions
      
      Content for command line users...

Nested Tabs

Create complex layouts with nested tab groups:

.. filter-tabs::

   .. tab:: Windows

      Choose your package manager:

      .. filter-tabs::

         .. tab:: Chocolatey
            choco install my-package

         .. tab:: Scoop  
            scoop install my-package

How It Works

This extension uses a pure CSS architecture with semantic HTML:

• Radio buttons provide the selection mechanism (hidden but accessible)
• CSS :checked selectors control panel visibility
• Fieldset/legend structure provides semantic grouping
• ARIA attributes enhance screen reader support
• Native keyboard navigation works through standard form controls

This approach ensures:

• Maximum compatibility across all browsers and assistive technologies
• Better performance with no JavaScript parsing or execution
• Enhanced security for environments with strict Content Security Policies
• Simplified maintenance with fewer dependencies and potential conflicts

Browser Support

Works in all modern browsers that support:

• CSS3 selectors (:checked, attribute selectors)
• Basic ARIA attributes
• HTML5 form elements

This includes all browsers from the last 10+ years.

Development

Quick Setup

git clone https://github.com/aputtu/sphinx-filter-tabs.git
cd sphinx-filter-tabs
./scripts/setup_dev.sh

This creates a virtual environment and builds the documentation.

Note: Always activate the virtual environment before running any development commands, otherwise your shell may pick up a different Python installation (e.g. a system or conda Python) and commands like pytest will fail:

source venv/bin/activate

Development Commands

# Activate virtual environment
source venv/bin/activate

# Run tests
pytest

# Build documentation
./scripts/dev.sh html

# Run tests across multiple Sphinx versions
tox

# Clean build and start fresh
./scripts/dev.sh clean-all

# Export project structure for analysis
./scripts/export-project.sh

Testing

The project includes comprehensive tests covering:

• Basic tab functionality and content visibility
• Accessibility features and ARIA compliance
• Nested tabs and complex layouts
• Multiple output formats (HTML, LaTeX, plain text, man, texinfo)
• Edge cases: duplicate names, empty tabs, multiple defaults, large tab groups

Tests run automatically on:

• Python versions 3.10, 3.11, 3.12, 3.13, 3.14
• Sphinx versions 7.0, 7.4, 8.0, 8.2, 9.0, 9.1
• 100% Code Coverage across all package modules
• Multiple operating systems via GitHub Actions

# Run the full test suite
tox

# Run linting (ruff) and type checking (mypy)
tox -e lint
tox -e mypy

Architecture

The extension is organized as a modular Python package:

• filter_tabs/ - Core logic split into focused modules (nodes.py, directives.py, render_html.py, etc.)
• filter_tabs/static/ - Pure CSS styling and functionality

The logic is distributed across dedicated modules for nodes, directives, transforms, and builders, ensuring a clean and maintainable codebase.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: pytest
5. Submit a pull request

License

GNU General Public License v3.0. See LICENSE for details.

Changelog

See CHANGELOG.md for version history and migration notes.

Support

• Documentation: https://aputtu.github.io/sphinx-filter-tabs/
• Issues: https://github.com/aputtu/sphinx-filter-tabs/issues
• PyPI: https://pypi.org/project/sphinx-filter-tabs/