Sphinx、reStructuredText 如何显示/隐藏代码片段

Question

Sphinx、reStructuredText 如何显示/隐藏代码片段

code-snippetsshow-hidepython-sphinxrestructuredtext

34

我一直在使用Sphinx和reStructuredText记录软件包的文档。

我的文档中有一些很长的代码片段。我希望它们默认情况下是隐藏的，而有一个小的“显示/隐藏”按钮可以展开它们(Example)。

有没有一种标准的方法来实现这个？

- Adam Matan

9个回答

26

您可以通过将代码包含在两个原始HTML指令中来使用内置的HTML可折叠details标签。

.. raw:: html

   <details>
   <summary><a>big code</a></summary>

.. code-block:: python

   lots_of_code = "this text block"

.. raw:: html

   </details>

生成：

<details>
<summary><a>big code</a></summary>
<pre>lots_of_code = "this text block"</pre>
</details>

- Epic Wink

6

我认为最简单的方法是创建一个自定义的Sphinx主题，其中您可以告诉特定的HTML元素具有此功能。在这里使用一些JQuery会很有帮助。

但是，如果您想要在reStructuredText标记中指定此功能，您需要执行以下操作之一：

- 将此功能包含在Sphinx本身中 - 在Sphinx/docutils扩展中实现它，然后创建一个知道此功能的Sphinx主题。

这需要更多的工作，但会给您更多的灵活性。

- Kevin Horn

2

你能分享一下你是如何开发Sphinx文档中的“显示/隐藏”功能的吗？ - shahjapan

6

有一个非常简单的扩展程序可以提供这个功能：https://github.com/scopatz/hiddencode

对我来说，它运行得相当不错。

- Martin Quinson

5

云雾主题有自定义指令html-toggle，提供可切换的部分。从他们的网页中引用：

您可以使用..rst-class:: html-toggle将节标记为可折叠，在html下默认将该节折叠，并在标题右侧显示“显示节”切换链接。

这里是他们的测试演示页面链接。

- Phil

3

sphinx-togglebutton

看起来自从这个问题被回答以来，一个新的sphinx扩展程序已经被制作出来了。

运行：pip install sphinx-togglebutton

添加到conf.py

extensions = [
...
'sphinx_togglebutton'
...
]

在rst源文件中：

.. admonition:: Show/Hide
  :class: dropdown

  hidden message

- AshkanPakzad

1

既然上述方法都对我无效，下面是最终解决方案：

create a file substitutions.rst in your source-directory with the following content:

.. |toggleStart| raw:: html

   <details>
   <summary><a> the title of the collapse-block </a></summary>

.. |toggleEnd| raw:: html

   </details>
   <br/>

add the following line at the beginning of every file you want to use add collapsible blocks
```
..include:: substitutions.rst
```

now, to make a part of the code collapsible simply use:

|toggleStart|

the text you want to collapse
..code-block:: python 
    x=1

|toggleEnd|

- raphael

这基本上与 https://dev59.com/13E95IYBdhLWcg3wGqEH#60394068 相同。 - mzjn

@mzjn 是的，但我认为使用替换可以使其更紧凑和易读（特别是如果您有许多具有相同标题文本的可折叠段）。 - raphael

0

另一个选项是sphinx-design扩展中的下拉指令。从文档中可以看到：

安装sphinx-design

pip install sphinx-design

将扩展名添加到conf.py中的extensions列表中

extensions = ["sphinx_design"]

在您的rst文件中使用dropdown指令：

.. dropdown::

    Dropdown content

- Matt Pitkin

0

自从0.20版本（2023-05-09）起，Docutils HTML5编写器支持详细披露元素。有关源rST，请参阅https://docutils.sourceforge.io/test/functional/input/data/html5-features.txt。

- G. Milde

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- pbauer · Accepted Answer

你不需要自定义主题。使用内置指令container，它允许你为块添加自定义CSS类，并覆盖现有主题以添加一些JavaScript来添加显示/隐藏功能。

这是_templates/page.html:

{% extends "!page.html" %}

{% block footer %}
 <script type="text/javascript">
    $(document).ready(function() {
        $(".toggle > *").hide();
        $(".toggle .header").show();
        $(".toggle .header").click(function() {
            $(this).parent().children().not(".header").toggle(400);
            $(this).parent().children(".header").toggleClass("open");
        })
    });
</script>
{% endblock %}

这是 _static/custom.css：

.toggle .header {
    display: block;
    clear: both;
}

.toggle .header:after {
    content: " ▶";
}

.toggle .header.open:after {
    content: " ▼";
}

将以下内容添加到conf.py文件中：

This is added to conf.py:

def setup(app):
    app.add_css_file('custom.css')

现在您可以显示/隐藏代码块。

.. container:: toggle

    .. container:: header

        **Show/Hide Code**

    .. code-block:: xml
       :linenos:

       from plone import api
       ...

我在这里使用非常类似的东西进行练习：https://training.plone.org/5/mastering-plone/about_mastering.html#exercises