Sphinx, reStructuredText Code-Snippets anzeigen/verbergen

Question

Ich habe ein Softwarepaket mit Sphinx und reStructuredText dokumentiert.

In meinen Dokumenten gibt es einige lange Code-Schnipsel. Ich möchte in der Lage sein, sie als Standard mit einem kleinen "Einblenden/Ausblenden" -Button zu verbergen, der sie erweitern würde (Example).

Gibt es einen Standard Weg, das zu tun?

Answer 1

Ich denke, der einfachste Weg, dies zu tun wäre, ein eigenes Sphinx-Thema zu erstellen, in dem Sie bestimmten HTML-Elementen sagen, diese Funktionalität zu haben. Ein kleiner JQuery würde hier einen langen Weg gehen.

Wenn aber Sie in der Lage sein wollen, dass diese Auszeichnung in Ihrem reStructuredText angeben, müssten Sie entweder

• bekommen so etwas selbst in Sphinx enthalten oder
• implementieren es in einer Sphinx/docutils Erweiterung ... und erstelle dann ein Sphinx-Thema, das über diese Funktionalität Bescheid weiß.

Dies wäre ein bisschen mehr Arbeit, aber würde Ihnen mehr Flexibilität geben.

Answer 2

Sie benötigen kein benutzerdefiniertes Thema. Verwenden Sie die integrierte Direktive container, mit der Sie benutzerdefinierte CSS-Klassen zu Blöcken hinzufügen und das vorhandene Thema überschreiben können, um JavaScript hinzuzufügen, um die show/hide-Funktionalität hinzuzufügen.

Dies ist _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 %} 

Dies ist _static/custom.css:

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

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

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

Jetzt können Sie einen Code-Block ein-/auszublenden.

.. container:: toggle 

    .. container:: header 

     **Show/Hide Code** 

    .. code-block:: xml 
     :linenos: 

     from plone import api 
     ... 

ich etwas sehr ähnlich für Übungen hier: https://training.plone.org/5/mastering_plone/about_mastering.html#exercises

Answer 3

Die Wolke Sphinx Thema hat benutzerdefinierte Richtlinie html-toggle die togglebar Abschnitte zur Verfügung stellt. Zitat aus ihrem web page:

können Sie markieren Abschnitte mit .. rst-class:: html-toggle, die den Abschnitt Standard machen zu werden unter html zusammenbrach, mit einem „Show Abschnitt“ Gelenkstangenabstützbauteil rechts von dem Titel.

Here ist ein Link zu ihrer Testdemonstrationsseite.