Extension `runblock`¶

À faire

Cette extension Sphinx autorun (runblock) semble cassée avec les dernières versions de Sphinx. En même temps, elle a 12/15 ans… Je n’ai pas le temps de la réparer, ni d’essayer runcmd.

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.

Voir aussi

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 :

.. runblock:: pycon

    >>> for i in range(5):
    …  print(i)

produira la sortie suivante :

On peut aussi vérifier la version de Python utilisée par l’extension :

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 :

Ou bien une liste des fichiers reStructuredText (.rst, sources de chaque de ces pages web) dans le dossier courant :

On peut chercher les 10 plus long noms de fichiers (parmi les fichiers reStructuredText) dans le dossier courant :

Ou bien encore, on peut réaliser une signature GPG (à la volée) du fichier courant (pour plus d’infos sur GPG, voir pgp.html) :

Autres exemples divers¶

figlet pour afficher du texte en ASCII art :

Mon script bin/series.sh 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 :

État du dépôt git (montre quels fichiers sont nouveaux (N), modifiés (M) ou supprimés (D)) :

Un truc débile avec un élan (cf. Bohort : « Non, moi ça m’évoque plutôt un élan » via publis/.quotes.txt) :

On peut essayer une idée encore plus folle, afficher une image en texte ASCII :

Et la même en plus gros (au fait, cette image est l’icone de ce site web) :

Quelques statistiques sur ce dépôt git :

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) :

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 :

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) :

# 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 :

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 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 manuellement pkg_resources = None (à la ligne 41). C’est sale mais ça corrige le bug…

Extension runblock¶