code-snippets - Sphinx、reStructuredText 显示/隐藏代码片段

Question

我一直在使用Sphinx和reStructuredText记录一个软件包。

在我的文档中，有一些长代码片段。我希望能够将它们默认隐藏，并带有一个可以展开它们的小“显示/隐藏”按钮（示例）。

有没有标准的方法来做到这一点？

Answer 1

您不需要自定义主题。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：

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

Answer 2

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

.. 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>

Answer 3

我认为最简单的方法是创建一个自定义 Sphinx 主题，您可以在其中告诉某些 html 元素具有此功能。一个小 JQuery 在这里会有很长的路要走。

但是，如果您希望能够在 reStructuredText 标记中指定它，则需要

• 将这样的东西包含在 Sphinx 本身或
• 在 Sphinx/docutils 扩展中实现它……然后创建一个了解此功能的 Sphinx 主题。

这将是更多的工作，但会给你更多的灵活性。

Answer 4

有一个非常简单的扩展提供了该功能：https ://github.com/scopatz/hiddencode

它对我来说效果很好。

Answer 5

云狮身人面像主题具有html-toggle提供可切换部分的自定义指令。引用他们的网页：

您可以使用 标记部分.. rst-class:: html-toggle，这将使部分默认折叠在 html 下，标题右侧有一个“显示部分”切换链接。

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

Answer 6

由于上述方法似乎都不适合我，因此我最终解决了它：

1. 在源目录中创建一个包含substitutions.rst以下内容的文件：

   .. |toggleStart| raw:: html
   
      <details>
      <summary><a> the title of the collapse-block </a></summary>
   
   .. |toggleEnd| raw:: html
   
      </details>
      <br/>
   

2. 在要使用的每个文件的开头添加以下行添加可折叠块

   ..include:: substitutions.rst
   

3. 现在，要使部分代码可折叠，只需使用：

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