Question

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

在我的文档中，有一些很长的代码片段。我希望能够将它们隐藏为默认设置，并使用一个“显示/隐藏”按钮来展开它们（Example）。

有没有一种标准方法可以做到这一点？

Answer 1

您不需要自定义主题。使用内置指令container，它允许您向块添加自定义css类，并覆盖现有主题以添加一些javascript以添加show / hide功能。

这是_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_stylesheet('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

您可以通过将代码包装在两个原始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>

Answer 3

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

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

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

这会更多一些工作，但会给你更大的灵活性。

Answer 4

云sphinx主题具有自定义指令html-toggle，可提供可切换的部分。引用他们的web page：

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

Here是指向其测试演示页的链接。

Answer 5

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

对我来说效果很好。

Sphinx，reStructuredText显示/隐藏代码片段

5 个答案: