Sphinx, reStructuredText show/hide code snippets

Question

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?

Answer 1

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_css_file('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