.. meta::
:description lang=fr: Test de l'extension ``runblock`` pour Sphinx
:description lang=en: Testing the ``autorun`` Sphinx extension
########################
Extension ``runblock``
########################
Je teste ici la fonctionnalité "expérimentale" de `Sphinx `_,
`l'extension autorun `_, qui donne une directive ``.. runblock::``,
qui permet d'exécuter du code lors de la génération de la page web.
.. seealso:: Pour une liste d'extensions Sphinx utiles, `cette page donne un bonne idée de ce qui existe `_ (en anglais).
Exemples
--------
pycon
~~~~~
La première directive est ``..runblock:: pycon``.
Elle fait appel au `langage Python `_,
mais utilise la syntaxe d'une session interactive de l'intérpreteur.
Par exemple, le code suivant :
.. code-block:: rst
.. runblock:: pycon
>>> for i in range(5):
… print(i)
produira la sortie suivante :
.. runblock:: pycon
>>> for i in range(5):
... print(i)
On peut aussi vérifier la version de Python utilisée par l'extension :
.. runblock:: pycon
>>> import sys
>>> print(sys.version)
Cette directive ``.. runblock:: pycon`` est intéressante, pour donner des exemples et de courtes démonstrations, dans des tutoriels ou de la documentation par exemple.
Mais, cette extension **runcode** permet aussi de faire plus !
------------------------------------------------------------------------------
Exemples plus intéressants
--------------------------
``.. runblock:: console``
~~~~~~~~~~~~~~~~~~~~~~~~~
Cette directive accepte la syntaxe d'un shell (``sh`` classique) ou de Bash, où le code est précédé d'un symbole *$ *.
Par exemple, la date courante et le dossier de travail courant :
.. runblock:: console
$ echo "Date : $(date). Dossier : $(pwd)."
Ou bien une liste des fichiers `reStructuredText `_ (``.rst``, sources de chaque de ces pages web) dans le dossier courant :
.. runblock:: console
$ ls -larth ./{,.}*.rst
On peut chercher les 10 plus long noms de fichiers (parmi les fichiers `reStructuredText`_) dans le dossier courant :
.. runblock:: console
$ for i in $(find -iname '*'.rst | sort); do echo "${#i} : $i" | sed s/'^\([0-9]\) '/'0\1 '/; done | sort | tail | awk '{ print $3 }'
Ou bien encore, on peut réaliser une signature *GPG* (*à la volée*) du fichier courant (pour plus d'infos sur *GPG*, voir ``_) :
.. runblock:: console
$ gpg --quiet -o - --armor --detach-sign runblock.fr.rst
Autres exemples divers
~~~~~~~~~~~~~~~~~~~~~~
*figlet* pour afficher du texte en ASCII art :
.. runblock:: console
$ figlet "C'est joli non ?"
Mon script ``_ permet de lire automatiquement l'épisode suivant
d'une série télé, et utilise un fichier *~/current* pour savoir quel dossier lire.
On peut s'en servir pour afficher quelle série télé je regarde en ce moment :
.. runblock:: console
$ echo -e "En ce moment, je regarde la série $(basename "$(cat /home/lilian/current | tr _ ' ')") :)"
État du dépôt git (montre quels fichiers sont nouveaux (*N*), modifiés (*M*) ou supprimés (*D*)) :
.. runblock:: console
$ git status --porcelain
Un truc débile avec un élan (cf. Bohort : "Non, moi ça m'évoque plutôt un élan" via ``_) :
.. runblock:: console
$ cowthink -W 160 -f /usr/share/cowsay/cows/moose.cow "Et vous trouvez ça drôle ?"
On peut essayer une idée encore plus folle, afficher une image **en texte ASCII** :
.. runblock:: console
$ convert ~/.link.ico jpg:- | jp2a -b - --size=31x20
Et la même en plus gros (*au fait*, cette image est `l'icone de ce site web `_) :
.. runblock:: console
$ convert ~/.link.ico jpg:- | jp2a -b - --size=62x30
Quelques statistiques sur `ce dépôt git `_ :
.. runblock:: console
$ echo "Nombre de commits par auteur (dans ce depot git) :"
$ git --no-pager shortlog -sn --all
Un calendrier montrant les jours d'activités de ce dépôt git (`avec cet autre script `_, si vous êtes curieux `cette web-page est une jolie version web de ce "calendrier" minimaliste `_) :
.. runblock:: console
$ git-cal --ascii
Des ajouts : OCaml ?
~~~~~~~~~~~~~~~~~~~~
Dans le fichier de configuration de Sphinx, `conf.py `_,
on peut facilement créer des raccourcis pour faciliter l'utilisation de cette extension **runblock**.
Il faut d'abord créér un *dictionnaire* vide appelé ``autorun_languages`` :
.. code-block:: python
autorun_languages = {}
Et ensuite ajouter une valeur ``truc`` (un programme valide, comme `gnuplot `_ ou `ocaml `_)
et ``truc_prefix_chars`` (taille des préfixes)
pour rendre utilisable la balise ``.. code-block:: truc`` dans les documents reStructuredText (dans *ce* projet seulement) :
.. code-block:: python
# Ajouter ça dans votre 'conf.py'
autorun_languages['ocaml'] = u'ocaml -stdin'
autorun_languages['ocaml_prefix_chars'] = 2
autorun_languages['ocaml_input_language'] = 'utf_8'
autorun_languages['ocaml_output_language'] = 'utf_8'
``.. runblock:: ocaml`` marche désormais
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Avec cette astuce, on peut désormais inclure facilement des exemples de code en OCaml :
.. runblock:: ocaml
# let rec f = function 0 -> 1 | n -> n *(f (n-1)) in
# print_int (f 11);;
# Printf.printf "\n OCaml version %s\n" Sys.ocaml_version;;
Pour plus de détails, cf. `le code source de l'extension autorun.py `_.
------------------------------------------------------------------------------
Bug étrange de ``pygments``
^^^^^^^^^^^^^^^^^^^^^^^^^^^
This ``runblock`` extension uses the great `pygments `_ Python library to color the code.
J'ai des fois vu ``pygments`` ou ``pygmentize`` se casser complètement, et la correction que je fais :red:`manuellement` est de supprimer
le support (annoncé comme expérimental) de ``pkg_resources``
dans le fichier `plugin.py `_ dans les sources de pygments,
en forçant :red:`manuellement` ``pkg_resources = None``
(`à la ligne 41 `_).
:red:`C'est sale` mais ça corrige le bug…
.. (c) Lilian Besson, 2011-2021, https://bitbucket.org/lbesson/web-sphinx/