Sphinx, reStructuredText afficher/masquer des extraits de code
j'ai documenté un paquet logiciel en utilisant Sphinx et reStructuredText.
dans Mes documents, il y a de longs extraits de code. Je veux pouvoir les avoir cachés par défaut, avec un petit bouton "Show / Hide" qui les développerait (Exemple).
y a-t-il un moyen standard de faire cela?
4 réponses
je pense que la façon la plus facile de faire cela serait de créer un thème Sphinx personnalisé dans lequel vous dites à certains éléments html d'avoir cette fonctionnalité. Un peu de JQuery ferait du chemin ici.
si, cependant, vous voulez pouvoir le spécifier dans votre markup reStructuredText, vous devez soit
- faire inclure une telle chose dans le Sphinx lui-même ou
- l'implémenter dans une extension Sphinx/docutils...et puis créer un thème Sphinx qui savait à propos de cette fonctionnalité.
Ce serait un peu plus de travail, mais vous donnera plus de flexibilité.
Vous n'avez pas besoin d'un thème personnalisé. Utiliser la directive container cela vous permet d'ajouter des classes CSS personnalisées aux blocs et d'Outrepasser le thème existant pour ajouter du javascript pour ajouter la fonctionnalité show/hide -.
C'est _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 %}
C'est _static/custom.css:
.toggle .header {
display: block;
clear: both;
}
.toggle .header:after {
content: " ▼";
}
.toggle .header.open:after {
content: " ▲";
}
Maintenant vous pouvez afficher / cacher un bloc de code.
.. container:: toggle
.. container:: header
**Show/Hide Code**
.. code-block:: xml
:linenos:
from plone import api
...
j'utilise quelque chose de très similaire pour les exercices ici: https://training.plone.org/5/mastering_plone/about_mastering.html#exercises
le thème cloud sphinx a une directive personnalisée html-toggle qui fournit des sections basculables. Pour citer leurs page web:
vous pouvez marquer les sections avec
.. rst-class:: html-toggle, ce qui fera que la section par défaut s'effondrera sous html, avec un lien à bascule "show section" à droite du titre.
Ici est un lien vers leur page de démonstration de test.
Il y a un très simpliste extension offrant exactement cette fonction: https://github.com/scopatz/hiddencode
Cela fonctionne plutôt bien pour moi.