Sphinx, reestructuredText show/ocultar fragmentos de código

Question

He estado documentando un paquete de software usando Esfinge y reestructuredText.

Dentro de mis documentos, hay algunos fragmentos de código largo. Quiero poder tenerlos ocultos como predeterminados, con un pequeño botón de "mostrar/ocultar" que los expandiría (Ejemplo).

¿Existe una forma estándar de hacerlo?

Answer 1

Creo que la forma más fácil de hacer esto sería crear un tema Sphinx personalizado en el que le dice a ciertos elementos HTML que tengan esta funcionalidad. Un pequeño jQuery iría mucho aquí.

Si, sin embargo, desea poder especificar esto en su marcado reestructuredText, necesitará

• Obtenga tal cosa incluida en Sphinx o
• Impléntelo en una extensión Sphinx/Docutils ... y luego cree un tema Sphinx que supiera sobre esta funcionalidad.

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

Answer 2

No necesitas un tema personalizado. Use la directiva incorporada container Eso le permite agregar clases CSS personalizadas a los bloques y anular el tema Existsting para agregar un JavaScript para agregar el programa/escondite.

Esto es _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 %}

Esto es _static/custom.css:

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

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

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

Esto se agrega a conf.py:

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

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

.. container:: toggle

    .. container:: header

        **Show/Hide Code**

    .. code-block:: xml
       :linenos:

       from plone import api
       ...

Uso algo muy similar para ejercicios aquí: https://training.plone.org/5/mastering_plone/about_mastering.html#exercises

Answer 3

El tema de la nube Sphinx tiene una directiva personalizada html-toggle que proporciona secciones toglables. Para citar de su página web:

Puedes marcar secciones con .. rst-class:: html-toggle, que hará que la sección sea predeterminada para colapsar en HTML, con un enlace de alternar "Show Section" a la derecha del título.

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

Answer 4

Hay una extensión muy simplista que proporciona exactamente esa característica: https://github.com/scopatz/hiddencode

Funciona bastante bien para mí.