Usage Example

Examples

Here is a live demonstration of the extension with the new simplified syntax.

Choose programming language: Python, C++, JavaScript

Python

Select Python tab

C++

Select C++ tab

JavaScript

Select JavaScript tab

This is general content visible regardless of the selected filter. It’s perfect for introductory text or information that applies to all tabs.

This panel shows content specific to Python.

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

This panel shows content specific to C++.

#include <iostream>

int main() {
    std::cout << "Hello from C++!" << std::endl;
    return 0;
}

This panel shows content specific to JavaScript.

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

Using ARIA Labels for Better Accessibility

For improved screen reader support, you can provide descriptive ARIA labels that give more context than the short visual tab names:

Choose interface: CLI, GUI

CLI

Select CLI tab

GUI

Select GUI tab

Choose your preferred installation method below.

Install using the command line:

# Using pip
pip install sphinx-filter-tabs

# Or using pipx for isolated installation
pipx install sphinx-filter-tabs

Install using Anaconda Navigator:

1. Open Anaconda Navigator

2. Go to Environments → base (root)

3. Change dropdown from “Installed” to “All”

4. Search for sphinx-filter-tabs

5. Check the checkbox and click “Apply”

Alternatively, use the Anaconda Prompt:

conda install -c conda-forge sphinx-filter-tabs

Providing a Custom Legend

For cases where the auto-generated legend (e.g., “Choose programming language…”) is not specific enough, you can provide a custom title for the entire tab group using the :legend: option.

Select Your Deployment Environment

Staging

Select Staging tab

Production

Select Production tab

This panel shows configuration for the staging environment. It’s used for testing before release.

This panel shows configuration for the production environment. This is the live, user-facing setup.

Source Code for Custom Legend

The following RST markup was used to create the above example:

.. filter-tabs::
   :legend: Select Your Deployment Environment

   .. tab:: Staging (default)

      This panel shows configuration for the **staging** environment.
      It's used for testing before release.

   .. tab:: Production

      This panel shows configuration for the **production** environment.
      This is the live, user-facing setup.

Nested Tabs

You can nest filter-tabs directives to create more complex layouts. Simply indent the inner tab set within a tab directive of the outer set.

Choose operating system: Windows, macOS, Linux

Windows

Select Windows tab

macOS

Select macOS tab

Linux

Select Linux tab

Windows installation instructions. Choose your package manager below:

Choose package manager: Pip, Conda

Pip

Select Pip tab

Conda

Select Conda tab

Install with pip on Windows:

# Basic installation
pip install sphinx-filter-tabs

# Or install with documentation dependencies
pip install sphinx-filter-tabs[docs]

Install with Conda on Windows:

# Install from conda-forge channel
conda install -c conda-forge sphinx-filter-tabs

# Or using mamba for faster resolution
mamba install -c conda-forge sphinx-filter-tabs

macOS installation instructions:

# Using Homebrew Python
pip3 install sphinx-filter-tabs

# Or using MacPorts
sudo port install py-sphinx-filter-tabs

Linux installation instructions:

# Debian/Ubuntu
sudo apt install python3-sphinx-filter-tabs

# Or using pip
pip install --user sphinx-filter-tabs

Large Tab Groups

There is no fixed limit on the number of tabs in a group. The panel-visibility CSS is generated at build time, scaled exactly to the tabs present in each build. The following example shows 12 tabs — a realistic count for a library that ships official clients for many languages.

Note

Tab groups above 15 will trigger a build warning encouraging you to consider restructuring. Groups above 20 are capped and produce a build error. For truly large sets of alternatives, a toctree or a comparison table is usually a better fit.

Install the client library for your language

Python

Select Python tab

JavaScript

Select JavaScript tab

TypeScript

Select TypeScript tab

Go

Select Go tab

Rust

Select Rust tab

Java

Select Java tab

Kotlin

Select Kotlin tab

C#

Select C# tab

Ruby

Select Ruby tab

PHP

Select PHP tab

Swift

Select Swift tab

Elixir

Select Elixir tab

pip install acme-client

npm install acme-client

npm install acme-client
# Type declarations are bundled — no @types package needed.

go get github.com/acme/acme-client-go

# Cargo.toml
[dependencies]
acme-client = "1.0"

<!-- pom.xml -->
<dependency>
  <groupId>com.acme</groupId>
  <artifactId>acme-client</artifactId>
  <version>1.0.0</version>
</dependency>

// build.gradle.kts
implementation("com.acme:acme-client:1.0.0")

dotnet add package Acme.Client

gem install acme-client

composer require acme/acme-client

// Package.swift
.package(url: "https://github.com/acme/acme-client-swift", from: "1.0.0")

# mix.exs
{:acme_client, "~> 1.0"}