Sphinx, reStructuredText mostra/nascondi frammenti di codice

Question

Ho documentato un pacchetto software utilizzando Sphinx e reStructuredText.

All'interno dei miei documenti ci sono alcuni frammenti di codice lunghi. Voglio essere in grado di averli nascosti come predefinito, con un piccolo pulsante "Mostra/Nascondi" che li espanderebbe (Example).

Esiste un modo standard per farlo?

Answer 1

Penso che il modo più semplice per farlo sarebbe quello di creare un tema Sphinx personalizzato in cui si dice ad alcuni elementi HTML di avere questa funzionalità. Un piccolo JQuery farebbe molto per arrivare qui.

Se invece si vuole essere in grado di specificare questo nel vostro markup reStructuredText, si avrebbe bisogno di uno

• ottenere una cosa del genere incluso nella Sfinge stessa o
• implementarlo in una sfinge/docutils estensione ... e quindi creare un tema Sfinge che conosceva questa funzionalità.

Questo sarebbe un po 'più di lavoro, ma ti darebbe maggiore flessibilità.

Answer 2

Non è necessario un tema personalizzato. Utilizzare la direttiva integrata container che consente di aggiungere css-classes personalizzate ai blocchi e sovrascrivere il tema existsting per aggiungere qualche javascript per aggiungere la funzionalità show/hide.

Questo è _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 %} 

Questo è _static/custom.css:

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

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

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

Ora è possibile mostrare/nascondere un blocco di codice.

.. container:: toggle 

    .. container:: header 

     **Show/Hide Code** 

    .. code-block:: xml 
     :linenos: 

     from plone import api 
     ... 

io uso qualcosa di molto simile per gli esercizi qui: https://training.plone.org/5/mastering_plone/about_mastering.html#exercises

Answer 3

La nube sfinge tema ha direttiva personalizzato html-toggle che fornisce sezioni toggleable. Per citare dal loro web page:

È possibile contrassegnare le sezioni con .. rst-class:: html-toggle, che renderà il default sezione per essere crollato sotto html, con una “parte spettacolo” collegamento a leva a destra del titolo.

Here è un collegamento alla pagina di dimostrazione del test.