sphinx code tabs
================
|Version| |License| |Documentation|
This is a Sphinx extension that adds a ``tabs`` directive for creating a
tabbed widget, allowing the user to switch between them. The individual tabs
can be code blocks or general content.
This can be used to e.g. show a snippet in multiple languages, display
instructions for alternative platforms, or switch between code and output.
|Screenshot|
Installation
------------
.. code-block:: bash
pip install sphinx_code_tabs
To enable the extension in sphinx, simply add the package name in your
``conf.py`` to the list of ``extensions``:
.. code-block:: python
extensions = [
...
'sphinx_code_tabs',
]
Usage
-----
By enabling the extension you get access to the ``tabs`` directive that
declares a notebook of code block alternatives.
The individual tabs are created with the ``tab`` or ``code-tab`` directives. A
``tab`` can contain arbitrary restructuredText, while a ``code-tab`` acts like
a ``code-block`` and accepts all corresponding arguments. Both types of tabs
can appear in the same notebook.
The ``:selected:`` option allows to switch to a specified tab at start. By
default, the first tab is used.
For example, this is the source of above example:
.. code-block:: rst
.. tabs::
.. code-tab:: bash
echo "Hello, *World*!"
.. code-tab:: c
:caption: C/C++
:emphasize-lines: 2
#include <stdio.h>
int main() { printf("Hello, *World*!\n"); }
.. code-tab:: python
print("Hello, *World*!")
.. tab:: Output
:selected:
Hello, *World*!
Grouped tabs
~~~~~~~~~~~~
The ``tabs`` directive takes an optional argument that identifies its *tab
group*. Within a given tab group, all notebooks will automatically be switched
to the same tab number if the tab is switched in one member of the group.
It is your responsibility to make sure that each member of the group has the
same number and ordering of tabs. Example:
|Tabgroup|
Source:
.. code-block:: rst
.. tabs:: lang
.. code-tab:: bash
echo "Hello, group!"
.. code-tab:: python
print("Hello, group!")
.. tabs:: lang
.. code-tab:: bash
echo "Goodbye, group!"
.. code-tab:: python
print("Goodbye, group!")
Alternatives
------------
After creating this package, I found other packages which are functionally
similar or equivalent. You may want to check them out if sphinx-code-tabs
doesn't fit your needs:
- sphinx_tabs_
- sphinx_inline_tabs_
.. _sphinx_tabs: https://pypi.org/project/sphinx-tabs/
.. _sphinx_inline_tabs: https://pypi.org/project/sphinx-inline-tabs/
.. |Documentation| image:: https://readthedocs.org/projects/sphinx-code-tabs/badge/?version=latest
:target: https://sphinx-code-tabs.readthedocs.io/en/latest/
:alt: Documentation
.. |License| image:: https://img.shields.io/pypi/l/sphinx-code-tabs.svg
:target: https://github.com/coldfix/sphinx-code-tabs/blob/main/UNLICENSE
:alt: License: Unlicense
.. |Version| image:: https://img.shields.io/pypi/v/sphinx-code-tabs.svg
:target: https://pypi.org/project/sphinx-code-tabs
:alt: Latest Version
.. |Screenshot| image:: https://raw.githubusercontent.com/coldfix/sphinx-code-tabs/main/screenshot1.webp
:target: https://sphinx-code-tabs.readthedocs.io/en/latest/#usage
:alt: Code tabs screenshot
.. |Tabgroup| image:: https://raw.githubusercontent.com/coldfix/sphinx-code-tabs/main/screenshot2.webp
:target: https://sphinx-code-tabs.readthedocs.io/en/latest/#grouped-tabs
:alt: Grouped tabs screenshot
CHANGES
-------
v0.5.4
~~~~~~
Date: 13.07.2023
- no changes, release needed to trigger a new build
v0.5.4
~~~~~~
Date: 28.06.2023
- declare extension as safe for parallel reads (#6)
v0.5.3
~~~~~~
Date: 28.11.2021
- fix CHANGES to appear in long description
v0.5.2
~~~~~~
Date: 28.11.2021
- fix ImportError triggered on readthedocs due to ancient sphinx version (v1.8)
v0.5.1
~~~~~~
Date: 28.11.2021
- update description for landing page
v0.5.0
~~~~~~
Date: 28.11.2021
- add ``tab`` directive for arbitrary (non-code) content
- add ``tabs`` directive and make ``code-tabs`` a backward-compatibility alias
of ``tabs``, to account for the new more general tab containers
- make the ``:title:`` option no longer required (wasn't enforced anyway by
sphinx)
- add grouped tabs
- make non-code tabs look better in latex output by boxing them like listings
v0.4.0
~~~~~~
Date: 27.11.2021
- fix bug that selects all tab buttons on click (introduced in prerender
commit)
v0.3.0
~~~~~~
Date: 27.11.2021
- fix AssertionError if :title: option is missing (see #3)
- increase css specificity to fix big margins that have appeared due to some
CSS change in sphinx or rtd
- fix exception when building pdf documents (#1, #4)
- prerender tab hidden/selected state to avoid content reflow on page (re-)load
v0.2.0
~~~~~~
Date: 21.06.2021
- update css for sphinx 4
v0.1.0
~~~~~~
Date: 10.10.2020
- fix missing assets when using the extension on readthedocs
- add documentation along with visual example on readthedocs
v0.0.1
~~~~~~
Date: 10.10.2020
Initial version with basic functionality:
- all rendering is done by JS, no prerendering
- so far no "notebook-groups" that switch the language simultaneously
Raw data
{
"_id": null,
"home_page": "https://github.com/coldfix/sphinx-code-tabs",
"name": "sphinx-code-tabs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "sphinx extension alternative code-block tab notebook",
"author": "Thomas Gl\u00e4\u00dfle",
"author_email": "thomas@coldfix.de",
"download_url": "https://files.pythonhosted.org/packages/46/b0/c70a7de8d27d8bfd4cc5ca799f84e46c963fde48269572bd681a9980c348/sphinx_code_tabs-0.5.5.tar.gz",
"platform": "any",
"description": "sphinx code tabs\n================\n\n|Version| |License| |Documentation|\n\nThis is a Sphinx extension that adds a ``tabs`` directive for creating a\ntabbed widget, allowing the user to switch between them. The individual tabs\ncan be code blocks or general content.\n\nThis can be used to e.g. show a snippet in multiple languages, display\ninstructions for alternative platforms, or switch between code and output.\n\n|Screenshot|\n\n\nInstallation\n------------\n\n.. code-block:: bash\n\n pip install sphinx_code_tabs\n\nTo enable the extension in sphinx, simply add the package name in your\n``conf.py`` to the list of ``extensions``:\n\n.. code-block:: python\n\n extensions = [\n ...\n 'sphinx_code_tabs',\n ]\n\n\nUsage\n-----\n\nBy enabling the extension you get access to the ``tabs`` directive that\ndeclares a notebook of code block alternatives.\n\nThe individual tabs are created with the ``tab`` or ``code-tab`` directives. A\n``tab`` can contain arbitrary restructuredText, while a ``code-tab`` acts like\na ``code-block`` and accepts all corresponding arguments. Both types of tabs\ncan appear in the same notebook.\n\nThe ``:selected:`` option allows to switch to a specified tab at start. By\ndefault, the first tab is used.\n\nFor example, this is the source of above example:\n\n.. code-block:: rst\n\n .. tabs::\n\n .. code-tab:: bash\n\n echo \"Hello, *World*!\"\n\n .. code-tab:: c\n :caption: C/C++\n :emphasize-lines: 2\n\n #include <stdio.h>\n int main() { printf(\"Hello, *World*!\\n\"); }\n\n .. code-tab:: python\n\n print(\"Hello, *World*!\")\n\n .. tab:: Output\n :selected:\n\n Hello, *World*!\n\n\nGrouped tabs\n~~~~~~~~~~~~\n\nThe ``tabs`` directive takes an optional argument that identifies its *tab\ngroup*. Within a given tab group, all notebooks will automatically be switched\nto the same tab number if the tab is switched in one member of the group.\nIt is your responsibility to make sure that each member of the group has the\nsame number and ordering of tabs. Example:\n\n|Tabgroup|\n\nSource:\n\n.. code-block:: rst\n\n .. tabs:: lang\n\n .. code-tab:: bash\n\n echo \"Hello, group!\"\n\n .. code-tab:: python\n\n print(\"Hello, group!\")\n\n\n .. tabs:: lang\n\n .. code-tab:: bash\n\n echo \"Goodbye, group!\"\n\n .. code-tab:: python\n\n print(\"Goodbye, group!\")\n\n\nAlternatives\n------------\n\nAfter creating this package, I found other packages which are functionally\nsimilar or equivalent. You may want to check them out if sphinx-code-tabs\ndoesn't fit your needs:\n\n- sphinx_tabs_\n- sphinx_inline_tabs_\n\n.. _sphinx_tabs: https://pypi.org/project/sphinx-tabs/\n.. _sphinx_inline_tabs: https://pypi.org/project/sphinx-inline-tabs/\n\n\n.. |Documentation| image:: https://readthedocs.org/projects/sphinx-code-tabs/badge/?version=latest\n :target: https://sphinx-code-tabs.readthedocs.io/en/latest/\n :alt: Documentation\n\n.. |License| image:: https://img.shields.io/pypi/l/sphinx-code-tabs.svg\n :target: https://github.com/coldfix/sphinx-code-tabs/blob/main/UNLICENSE\n :alt: License: Unlicense\n\n.. |Version| image:: https://img.shields.io/pypi/v/sphinx-code-tabs.svg\n :target: https://pypi.org/project/sphinx-code-tabs\n :alt: Latest Version\n\n.. |Screenshot| image:: https://raw.githubusercontent.com/coldfix/sphinx-code-tabs/main/screenshot1.webp\n :target: https://sphinx-code-tabs.readthedocs.io/en/latest/#usage\n :alt: Code tabs screenshot\n\n.. |Tabgroup| image:: https://raw.githubusercontent.com/coldfix/sphinx-code-tabs/main/screenshot2.webp\n :target: https://sphinx-code-tabs.readthedocs.io/en/latest/#grouped-tabs\n :alt: Grouped tabs screenshot\n\nCHANGES\n-------\n\nv0.5.4\n~~~~~~\nDate: 13.07.2023\n\n- no changes, release needed to trigger a new build\n\n\nv0.5.4\n~~~~~~\nDate: 28.06.2023\n\n- declare extension as safe for parallel reads (#6)\n\n\nv0.5.3\n~~~~~~\nDate: 28.11.2021\n\n- fix CHANGES to appear in long description\n\n\nv0.5.2\n~~~~~~\nDate: 28.11.2021\n\n- fix ImportError triggered on readthedocs due to ancient sphinx version (v1.8)\n\n\nv0.5.1\n~~~~~~\nDate: 28.11.2021\n\n- update description for landing page\n\n\nv0.5.0\n~~~~~~\nDate: 28.11.2021\n\n- add ``tab`` directive for arbitrary (non-code) content\n- add ``tabs`` directive and make ``code-tabs`` a backward-compatibility alias\n of ``tabs``, to account for the new more general tab containers\n- make the ``:title:`` option no longer required (wasn't enforced anyway by\n sphinx)\n- add grouped tabs\n- make non-code tabs look better in latex output by boxing them like listings\n\n\nv0.4.0\n~~~~~~\nDate: 27.11.2021\n\n- fix bug that selects all tab buttons on click (introduced in prerender\n commit)\n\n\nv0.3.0\n~~~~~~\nDate: 27.11.2021\n\n- fix AssertionError if :title: option is missing (see #3)\n- increase css specificity to fix big margins that have appeared due to some\n CSS change in sphinx or rtd\n- fix exception when building pdf documents (#1, #4)\n- prerender tab hidden/selected state to avoid content reflow on page (re-)load\n\n\nv0.2.0\n~~~~~~\nDate: 21.06.2021\n\n- update css for sphinx 4\n\n\nv0.1.0\n~~~~~~\nDate: 10.10.2020\n\n- fix missing assets when using the extension on readthedocs\n- add documentation along with visual example on readthedocs\n\n\nv0.0.1\n~~~~~~\nDate: 10.10.2020\n\nInitial version with basic functionality:\n\n- all rendering is done by JS, no prerendering\n- so far no \"notebook-groups\" that switch the language simultaneously\n",
"bugtrack_url": null,
"license": "Unlicense",
"summary": "Sphinx extension for adding alternative code-blocks as selectable tabs",
"version": "0.5.5",
"project_urls": {
"Bug Tracker": "https://github.com/coldfix/sphinx-code-tabs/issues",
"Documentation": "https://sphinx-code-tabs.readthedocs.io",
"Download": "https://pypi.org/project/sphinx_code_tabs",
"Homepage": "https://github.com/coldfix/sphinx-code-tabs",
"Source Code": "https://github.com/coldfix/sphinx-code-tabs"
},
"split_keywords": [
"sphinx",
"extension",
"alternative",
"code-block",
"tab",
"notebook"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe815508858d971e5170ef4279de6cc805df3206737bfd86f697aa4a9e1e88e3",
"md5": "fb12374833e7d2f67d4d61355f4dd8db",
"sha256": "e2cabdcc02b5897b399f6bca36557ce050d2fb7d095c01292b41ad34f1ce2ef0"
},
"downloads": -1,
"filename": "sphinx_code_tabs-0.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb12374833e7d2f67d4d61355f4dd8db",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 8247,
"upload_time": "2023-07-13T10:53:31",
"upload_time_iso_8601": "2023-07-13T10:53:31.167510Z",
"url": "https://files.pythonhosted.org/packages/fe/81/5508858d971e5170ef4279de6cc805df3206737bfd86f697aa4a9e1e88e3/sphinx_code_tabs-0.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "46b0c70a7de8d27d8bfd4cc5ca799f84e46c963fde48269572bd681a9980c348",
"md5": "e712bd42480737f99092dc31aef74f8c",
"sha256": "150acc5190ce3b3d2378af02dc3fb651d32cbfb924a5ed37681418aa7520acea"
},
"downloads": -1,
"filename": "sphinx_code_tabs-0.5.5.tar.gz",
"has_sig": false,
"md5_digest": "e712bd42480737f99092dc31aef74f8c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 9909,
"upload_time": "2023-07-13T10:53:32",
"upload_time_iso_8601": "2023-07-13T10:53:32.948096Z",
"url": "https://files.pythonhosted.org/packages/46/b0/c70a7de8d27d8bfd4cc5ca799f84e46c963fde48269572bd681a9980c348/sphinx_code_tabs-0.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-13 10:53:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "coldfix",
"github_project": "sphinx-code-tabs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-code-tabs"
}
JSON
