Sphinx, reStructuredText show/hide code snippets
Solution 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.
Solution 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_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
Solution 3
You can use the built-in HTML collapsible details
tag by wrapping the code in two raw HTML directives
.. raw:: html
<details>
<summary><a>big code</a></summary>
.. code-block:: python
lots_of_code = "this text block"
.. raw:: html
</details>
Produces:
<details>
<summary><a>big code</a></summary>
<pre>lots_of_code = "this text block"</pre>
</details>
Solution 4
There is a very simplistic extension providing exactly that feature: https://github.com/scopatz/hiddencode
It works rather well for me.
Solution 5
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.
![Adam Matan](https://i.stack.imgur.com/QG9pG.jpg?s=256&g=1)
Adam Matan
Team leader, developer, and public speaker. I build end-to-end apps using modern cloud infrastructure, especially serverless tools. My current position is R&D Manager at Corvid by Wix.com, a serverless platform for rapid web app generation. My CV and contact details are available on my Github README.
Updated on June 06, 2022Comments
-
Adam Matan about 2 years
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?