Sphinx, reStructuredText muestra/oculta fragmentos de código

Question

He estado documentando un paquete de software usando Sphinx y reStructuredText.

Dentro de mis documentos, hay algunos fragmentos de código largos. Quiero poder ocultarlos por defecto, con un pequeño botón "Mostrar/Ocultar" que los expandiría (Example).

¿Hay una forma estándar de hacerlo?

Answer 1

Creo que la manera más fácil de hacerlo sería crear un tema personalizado de Sphinx en el que le diga a ciertos elementos html que tengan esta funcionalidad. Un poco de JQuery podría recorrer un largo camino hasta aquí.

Si por el contrario desea ser capaz de especificar esto en su margen de beneficio reStructuredText, que tendría que sea

• conseguir tal cosa incluidas en Sphinx sí mismo o
• implementarlo en una esfinge/docutils extensión ... y luego crear un tema de Sphinx que conociera acerca de esta funcionalidad.

Esto sería un poco más de trabajo, pero le daría más flexibilidad.

Answer 2

No necesita un tema personalizado. Use la directiva incorporada container que le permite agregar clases css personalizadas a bloques y anular el tema existente para agregar algún javascript para agregar la funcionalidad show/hide.

Ésta es _templates/page.html:

{% extends "!page.html" %} 

{% set css_files = css_files + ["_static/custom.css"] %} 

{% 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 %} 

Esta es _static/custom.css:

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

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

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

Ahora usted puede mostrar/ocultar un bloque de código.

.. container:: toggle 

    .. container:: header 

     **Show/Hide Code** 

    .. code-block:: xml 
     :linenos: 

     from plone import api 
     ... 

utilizo algo muy similar para los ejercicios aquí: Tema de la esfinge https://training.plone.org/5/mastering_plone/about_mastering.html#exercises

Answer 3

La nube tiene directiva personalizada que proporciona html-toggle secciones conmutable. Para citar de su web page:

Puede marcar secciones con .. rst-class:: html-toggle, lo que hará que el valor por defecto sección para plegarse bajo html, con un “show sección” barra de doble horquilla a la derecha del título.

Here es un enlace a su página de demostración de prueba.