Sphinx, reStructuredText show/hide code snippets

问题

I've been documenting a software package using Sphinx and reStructuredText.

Within my documents, there are some long code snippets. I want to be able to have them hidden as default, with a little "Show/Hide" button that would expand them (Example).

Is there a standard way to do that?

回答1:

I think the easiest way to do this would be to create a custom Sphinx theme in which you tell certain html elements to have this functionality. A little JQuery would go a long way here.

If, however you want to be able to specify this in your reStructuredText markup, you would need to either

get such a thing included in Sphinx itself or
implement it in a Sphinx/docutils extension...and then create a Sphinx theme which knew about this functionality.

This would be a bit more work, but would give you more flexibility.

回答2:

You don't need a custom theme. Use the built-in directive container that allows you to add custom css-classes to blocks and override the existsting theme to add some javascript to add the show/hide-functionality.

This is _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 %}

This is _static/custom.css:

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

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

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

This is added to conf.py:

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

Now you can show/hide a block of code.

.. container:: toggle

    .. container:: header

        **Show/Hide Code**

    .. code-block:: xml
       :linenos:

       from plone import api
       ...

I use something very similar for exercises here: https://training.plone.org/5/mastering_plone/about_mastering.html#exercises

回答3:

The cloud sphinx theme has custom directive html-toggle that provides toggleable sections. To quote from their web page:

You can mark sections with .. rst-class:: html-toggle, which will make the section default to being collapsed under html, with a “show section” toggle link to the right of the title.

Here is a link to their test demonstration page.