4.3. 选项卡插件 sphinx_tabs.tabs#

更新时间: 2021-12-21, 11:46:56 | sphinx-tabs 版本：3.2.0

构建 HTML 时在 Sphinx 文档中创建选项卡式内容。本文章参考 Sphinx Tabs 官方文档 。

需要注意的是， sphinx_tabs.tabs 插件相较于 MyST ，更适合在 .rst 文件中被解析，所以如果需要在 MyST 或 MyST-NB 解析下的 .md 文件下使用选项卡，那么建议使用另一个功能更加强大的插件 Sphinx Design 。

Warning

sphinx-tabs 3.2.0 requires docutils~=0.16.0；但是由于考虑到将来可能要使用 将 Markdown 文件包含到 rST 文件中 的功能，而此功能需要依赖 docutils >=0.17，所以此插件版本可能会被笔者作为过时版本。

4.3.1. 安装#

pip install sphinx-tabs

要在 Sphinx 中启用扩展，请将以下内容添加到您的 conf.py：

extensions = ['sphinx_tabs.tabs']

Read The Docs 来构建文档时的注意事项

如果您使用 Read The Docs 来构建文档，则必须添加扩展作为要求。请将 sphinx-tabs 添加到项目根目录或 docs 文件夹中的 requirements.txt。

4.3.2. 在 reST 语法使用#

.. tabs::

   .. tab:: Apples

      Apples are green, or sometimes red.

   .. tab:: Pears

      Pears are green.

   .. tab:: Oranges

      Oranges are orange.

运行结果如下：

Apples are green, or sometimes red.

更多指令

sphinx-tabs.tabs 插件还有 group-tab 指令 和 code-tab 指令与 tabs 指令嵌套使用的语法，在这里就不加以详述，若有学习意向可 前往 sphinx-tabs 官方文档查看 。

在 rst 文件中使用 Sphinx Design 插件实现选项卡功能

.. tab-set::

    .. tab-item:: Label1

        Content 1

    .. tab-item:: Label2

        Content 2

运行结果如下：

Content 1

Content 2

建议使用另一个功能更加强大的插件 Sphinx Design 。

4.3.3. 使用 MyST Parser 的 Markdown 语法使用#

::::{tabs}

:::{tab} Label1

Content 1
:::

:::{tab} Label2

Content 2
:::

::::

运行结果如下：(Markdown形式的语法参考RST形式的,需要注意的是这个指令和内容之间必须要有空行)

Content 1

4.3.4. 实际应用#

由于 sphinx tabs 插件的在使用过程中使用到指令的多层嵌套，将其转换为 MyST 语法格式会变得难以阅读，所以采用引用 .rst 文件的形式使用在 .md 文件中。

```{eval-rst}
.. include:: ./example/tab/tab-code.rst
```

代码实际运行界面 可点击源码界面的下载按钮查看实现源码, 引用下的代码运行效果如下

```{admonition} What could be inside this warning?
:class: warning, dropdown

A whale of a joke!

![A whale of a joke](https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif)

(sorry)
```