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

Question

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

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

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

Answer 1

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

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

• 得到这样的东西包括在狮身人面像本身或
• 在Sphinx / docutils扩展中实现它...然后创建一个了解此功能的Sphinx主题。

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

Answer 2

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

这是_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 3

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

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

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

Answer 4

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

它对我来说效果很好。