{"id":3278,"library":"sphinx-tabs","title":"Tabbed views for Sphinx","description":"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.","status":"active","version":"3.5.0","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-tabs","tags":["sphinx","documentation","tabs","extension","restructuredtext"],"install":[{"cmd":"pip install sphinx-tabs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core documentation generator, version >=7 is required for sphinx-tabs 3.5.0.","package":"Sphinx","optional":false},{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"note":"Add 'sphinx_tabs.tabs' to the 'extensions' list in your conf.py to enable the extension.","symbol":"sphinx_tabs.tabs","correct":"extensions = ['sphinx_tabs.tabs']"}],"quickstart":{"code":"mkdir myproject\ncd myproject\nmkdir docs\ncd docs\nsphinx-quickstart  # Follow prompts, say 'y' to Separate source and build dirs\n# In docs/conf.py:\n# extensions = [\n#     'sphinx.ext.autodoc',\n#     'sphinx.ext.napoleon',\n#     'sphinx_tabs.tabs',\n# ]\n# html_theme = 'alabaster' # Or any other Sphinx theme\n\n# In docs/index.rst:\n# .. _index:\n#\n# Welcome to My Sphinx Tabs Project's documentation!\n# ==================================================\n#\n# .. tabs::\n#\n#     .. tab:: Python\n#\n#         .. code-block:: python\n#\n#             def hello_world():\n#                 print(\"Hello, Python!\")\n#\n#     .. tab:: Shell\n#\n#         .. code-block:: bash\n#\n#             echo \"Hello, Shell!\"\n#\n#     .. tab:: Markup\n#\n#         Hello from **reStructuredText**!\n#\n# This project demonstrates `sphinx-tabs` functionality.\n#\n# Indices and tables\n# ==================\n#\n# * :ref:`genindex`\n# * :ref:`modindex`\n# * :ref:`search`\n\n# Then build:\n# make html\n# Open _build/html/index.html","lang":"bash","description":"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."},"warnings":[{"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'`).","message":"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+.","severity":"breaking","affected_versions":">=3.5.0"},{"fix":"Refactor your reStructuredText to use `.. tab::` or `.. group-tab::` for content that needs to include other files, or manually embed the content directly.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Standardize tab labels across all `.. tabs::` blocks that share the same group name to ensure proper synchronization.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}