Sphinx, reStructuredText show/hide code snippets
I've been documenting a software package using Sphinx and r开发者_运维百科eStructuredText.
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?
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
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>
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.
There is a very simplistic extension providing exactly that feature: https://github.com/scopatz/hiddencode
It works rather well for me.
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.
sphinx-togglebutton
Looks like a new sphinx extension has been made to do just this since this question has been answered.
Run: pip install sphinx-togglebutton
Add to conf.py
extensions = [
...
'sphinx_togglebutton'
...
]
In rst source file:
.. admonition:: Show/Hide
:class: dropdown
hidden message
since none of the above methods seem to work for me, here's how I solved it in the end:
create a file
substitutions.rst
in your source-directory with the following content:.. |toggleStart| raw:: html <details> <summary><a> the title of the collapse-block </a></summary> .. |toggleEnd| raw:: html </details> <br/>
add the following line at the beginning of every file you want to use add collapsible blocks
..include:: substitutions.rst
now, to make a part of the code collapsible simply use:
|toggleStart| the text you want to collapse ..code-block:: python x=1 |toggleEnd|
Another option is the dropdown directive in the sphinx-design extension. From the docs:
- Install sphinx-design
pip install sphinx-design
- Add the extension to
conf.py
in theextensions
list
extensions = ["sphinx_design"]
- Use the
dropdown
directive in your rst file:
.. dropdown::
Dropdown content
精彩评论