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.
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 !
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) :
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) :
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
Avec cette astuce, on peut désormais inclure facilement des exemples de code en OCaml :
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...