Testing the autorun Sphinx extension

In this page, I am testing an « experimental » feature of Sphinx, the autorun extension, which provides a .. runblock:: directive, to execute arbitrary code when generating a Sphinx-powered web-page.

Voir aussi

For a list of possibly useful Sphinx extensions, this page gives a good overview.

Examples

pycon

The first directive is ..runblock:: pycon. It uses the Python language, but accepts the syntax of an interactive interpreter session.

For instance, this snippet of code:

.. runblock:: pycon

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

will produce this output (raw included in the HTML web-page):


  File "<stdin>", line 2
    rint(i)
       ^
IndentationError: expected an indented block

We can also check which version of Python used by the extension:


3.6.7 (default, Oct 22 2018, 11:32:17) 
[GCC 8.2.0]

This .. runblock:: pycon directive is interesting to give example or short demonstration, when writing tutorials or documentation for instance.

But this runcode extension allows to do way more!


A few more interesting examples

.. runblock:: console

This directive accepts the syntax of a shell or Bash session, where the code starts with a *$ * symbol.

For instance, the current date and directory:

$ echo "Date: $(date). Directory: $(pwd)."
Date: lundi 11 février 2019, 11:54:54 (UTC+0100). Directory: /home/lilian/web-sphinx.

We can also ask for a list of the reStructuredText files .rst (the source code of each of these web-pages) in the current directory:

$ ls -larth ./{,.}*.rst
-rw-r--r-- 1 lilian lilian  727 juil.  8  2016 ./.special.rst
-rw-r--r-- 1 lilian lilian  650 janv. 30  2017 ./.javascript.fr.rst
-rw-r--r-- 1 lilian lilian  578 janv. 30  2017 ./.javascript.en.rst
-rw-r--r-- 1 lilian lilian  15K nov.  27 14:33 ./demo.rst
-rw-r--r-- 1 lilian lilian 4,5K nov.  27 14:33 ./iteri.fr.rst
-rw-r--r-- 1 lilian lilian 4,8K nov.  27 14:33 ./iteri.en.rst
-rw-r--r-- 1 lilian lilian  23K nov.  27 14:33 ./slides.rst
-rw-r--r-- 1 lilian lilian  912 nov.  27 14:33 ./self-quantified.fr.rst
-rw-r--r-- 1 lilian lilian  15K nov.  27 14:33 ./self-quantified.en.rst
lrwxrwxrwx 1 lilian lilian   21 nov.  27 14:34 ./TODO.rst -> /home/lilian/TODO.rst
lrwxrwxrwx 1 lilian lilian   22 nov.  27 14:34 ./admin.rst -> /home/lilian/admin.rst
lrwxrwxrwx 1 lilian lilian   14 nov.  27 14:34 ./affaires-voyage.en.rst -> packing.en.rst
lrwxrwxrwx 1 lilian lilian   19 nov.  27 14:34 ./apprendre-python.en.rst -> learn-python.en.rst
lrwxrwxrwx 1 lilian lilian   19 nov.  27 14:34 ./autostop.en.rst -> hitch-hiking.en.rst
lrwxrwxrwx 1 lilian lilian   30 nov.  27 14:34 ./ce-que-je-regarde-sur-youtube.en.rst -> what-i-watch-on-youtube.en.rst
lrwxrwxrwx 1 lilian lilian   15 nov.  27 14:34 ./enseignement.en.rst -> teaching.en.rst
lrwxrwxrwx 1 lilian lilian   15 nov.  27 14:34 ./hitch-hiking.fr.rst -> autostop.fr.rst
lrwxrwxrwx 1 lilian lilian   23 nov.  27 14:34 ./learn-python.fr.rst -> apprendre-python.fr.rst
lrwxrwxrwx 1 lilian lilian   15 nov.  27 14:34 ./recherche.en.rst -> research.en.rst
lrwxrwxrwx 1 lilian lilian   22 nov.  27 14:34 ./packing.fr.rst -> affaires-voyage.fr.rst
lrwxrwxrwx 1 lilian lilian   16 nov.  27 14:34 ./research.fr.rst -> recherche.fr.rst
lrwxrwxrwx 1 lilian lilian   19 nov.  27 14:34 ./teaching.fr.rst -> enseignement.fr.rst
lrwxrwxrwx 1 lilian lilian   36 nov.  27 14:34 ./what-i-watch-on-youtube.fr.rst -> ce-que-je-regarde-sur-youtube.fr.rst
-rw-r--r-- 1 lilian lilian 2,4K janv.  6 18:02 ./403.rst
-rw-r--r-- 1 lilian lilian 2,4K janv.  6 18:02 ./404.rst
-rw-r--r-- 1 lilian lilian 8,8K janv.  6 18:02 ./A953.rst
-rw-r--r-- 1 lilian lilian 2,5K janv.  6 18:02 ./ace2.rst
-rw-r--r-- 1 lilian lilian 1,8K janv.  6 18:02 ./ace.rst
-rw-r--r-- 1 lilian lilian 8,7K janv.  6 18:02 ./affaires-voyage.fr.rst
-rw-r--r-- 1 lilian lilian 3,6K janv.  6 18:02 ./alaskabombeh.en.rst
-rw-r--r-- 1 lilian lilian 3,3K janv.  6 18:02 ./alaskabombeh.fr.rst
-rw-r--r-- 1 lilian lilian  20K janv.  6 18:02 ./apk.en.rst
-rw-r--r-- 1 lilian lilian  23K janv.  6 18:02 ./apk.fr.rst
-rw-r--r-- 1 lilian lilian 5,9K janv.  6 18:02 ./apprendre-python.fr.rst
-rw-r--r-- 1 lilian lilian 8,9K janv.  6 18:02 ./autostop.fr.rst
-rw-r--r-- 1 lilian lilian 8,0K janv.  6 18:02 ./avoir.rst
-rw-r--r-- 1 lilian lilian  11K janv.  6 18:02 ./beacon.en.rst
-rw-r--r-- 1 lilian lilian  11K janv.  6 18:02 ./beacon.fr.rst
-rw-r--r-- 1 lilian lilian  15K janv.  6 18:02 ./bin.en.rst
-rw-r--r-- 1 lilian lilian  15K janv.  6 18:02 ./bin.fr.rst
-rw-r--r-- 1 lilian lilian 3,7K janv.  6 18:02 ./bitbucket-features.en.rst
-rw-r--r-- 1 lilian lilian 3,8K janv.  6 18:02 ./bitbucket-features.fr.rst
-rw-r--r-- 1 lilian lilian  17K janv.  6 18:02 ./blog-roll.en.rst
-rw-r--r-- 1 lilian lilian  17K janv.  6 18:02 ./blog-roll.fr.rst
-rw-r--r-- 1 lilian lilian 7,5K janv.  6 18:02 ./callme.en.rst
-rw-r--r-- 1 lilian lilian 7,4K janv.  6 18:02 ./callme.fr.rst
-rw-r--r-- 1 lilian lilian  17K janv.  6 18:02 ./ce-que-je-regarde-sur-youtube.fr.rst
-rw-r--r-- 1 lilian lilian 3,0K janv.  6 18:02 ./cookies.en.rst
-rw-r--r-- 1 lilian lilian 4,3K janv.  6 18:02 ./cookies.fr.rst
-rw-r--r-- 1 lilian lilian  22K janv.  6 18:02 ./cv.en.rst
-rw-r--r-- 1 lilian lilian  25K janv.  6 18:02 ./cv.fr.rst
-rw-r--r-- 1 lilian lilian 3,5K janv.  6 18:02 ./data-analysis-of-2-years-of-sms-2016-2017.en.rst
-rw-r--r-- 1 lilian lilian 3,9K janv.  6 18:02 ./data-analysis-of-2-years-of-sms-2016-2017.fr.rst
-rw-r--r-- 1 lilian lilian  984 janv.  6 18:02 ./dyndns.rst
-rw-r--r-- 1 lilian lilian  14K janv.  6 18:02 ./enseignement.fr.rst
-rw-r--r-- 1 lilian lilian  16K janv.  6 18:02 ./firefox-extensions.en.rst
-rw-r--r-- 1 lilian lilian  18K janv.  6 18:02 ./firefox-extensions.fr.rst
-rw-r--r-- 1 lilian lilian 2,1K janv.  6 18:02 ./folders.rst
-rw-r--r-- 1 lilian lilian 3,6K janv.  6 18:02 ./freedns.rst
-rw-r--r-- 1 lilian lilian 3,8K janv.  6 18:02 ./ga.en.rst
-rw-r--r-- 1 lilian lilian 3,8K janv.  6 18:02 ./ga.fr.rst
-rw-r--r-- 1 lilian lilian 7,2K janv.  6 18:02 ./gnuplot_embed.rst
-rw-r--r-- 1 lilian lilian  11K janv.  6 18:02 ./gnuplot.rst
-rw-r--r-- 1 lilian lilian 8,5K janv.  6 18:02 ./graph.en.rst
-rw-r--r-- 1 lilian lilian 8,7K janv.  6 18:02 ./graph.fr.rst
-rw-r--r-- 1 lilian lilian 7,7K janv.  6 18:02 ./hitch-hiking.en.rst
-rw-r--r-- 1 lilian lilian 8,2K janv.  6 18:02 ./index.en.rst
-rw-r--r-- 1 lilian lilian 8,7K janv.  6 18:02 ./index.fr.rst
-rw-r--r-- 1 lilian lilian 4,6K janv.  6 18:02 ./js.en.rst
-rw-r--r-- 1 lilian lilian 5,0K janv.  6 18:02 ./js.fr.rst
-rw-r--r-- 1 lilian lilian 3,0K janv.  6 18:02 ./latexonwindows.en.rst
-rw-r--r-- 1 lilian lilian 3,0K janv.  6 18:02 ./latexonwindows.fr.rst
-rw-r--r-- 1 lilian lilian 5,5K janv.  6 18:02 ./learn-python.en.rst
-rw-r--r-- 1 lilian lilian 6,1K janv.  6 18:02 ./math.rst
-rw-r--r-- 1 lilian lilian 4,2K janv.  6 18:02 ./matlab-clones.en.rst
-rw-r--r-- 1 lilian lilian 4,6K janv.  6 18:02 ./matlab-clones.fr.rst
-rw-r--r-- 1 lilian lilian 3,1K janv.  6 18:02 ./mount.en.rst
-rw-r--r-- 1 lilian lilian 3,6K janv.  6 18:02 ./mount.fr.rst
-rw-r--r-- 1 lilian lilian  16K janv.  6 18:02 ./NanoSyntax.rst
-rw-r--r-- 1 lilian lilian 5,7K janv.  6 18:02 ./ocaml_ace.rst
-rw-r--r-- 1 lilian lilian 3,1K janv.  6 18:02 ./ocaml.en.rst
-rw-r--r-- 1 lilian lilian 3,1K janv.  6 18:02 ./ocaml.fr.rst
-rw-r--r-- 1 lilian lilian 2,8K janv.  6 18:02 ./online-gnu-octave.en.rst
-rw-r--r-- 1 lilian lilian 3,1K janv.  6 18:02 ./online-gnu-octave.fr.rst
-rw-r--r-- 1 lilian lilian 7,6K janv.  6 18:02 ./opendns.en.rst
-rw-r--r-- 1 lilian lilian 8,2K janv.  6 18:02 ./opendns.fr.rst
-rw-r--r-- 1 lilian lilian 4,4K janv.  6 18:02 ./packing.en.rst
-rw-r--r-- 1 lilian lilian 4,7K janv.  6 18:02 ./pgp.en.rst
-rw-r--r-- 1 lilian lilian 7,6K janv.  6 18:02 ./pgp.fr.rst
-rw-r--r-- 1 lilian lilian 1,2K janv.  6 18:02 ./plume-air-paris.en.rst
-rw-r--r-- 1 lilian lilian 1,3K janv.  6 18:02 ./plume-air-paris.fr.rst
-rw-r--r-- 1 lilian lilian  14K janv.  6 18:02 ./projects.en.rst
-rw-r--r-- 1 lilian lilian  18K janv.  6 18:02 ./publis.en.rst
-rw-r--r-- 1 lilian lilian  19K janv.  6 18:02 ./publis.fr.rst
-rw-r--r-- 1 lilian lilian 7,0K janv.  6 18:02 ./python.rst
-rw-r--r-- 1 lilian lilian 8,1K janv.  6 18:02 ./README.rst
-rw-r--r-- 1 lilian lilian 1,3K janv.  6 18:02 ./rss.rst
-rw-r--r-- 1 lilian lilian 6,9K janv.  6 18:02 ./runblock.en.rst
-rw-r--r-- 1 lilian lilian 7,1K janv.  6 18:02 ./runblock.fr.rst
-rw-r--r-- 1 lilian lilian  512 janv.  6 18:02 ./sitemap.en.rst
-rw-r--r-- 1 lilian lilian  562 janv.  6 18:02 ./sitemap.fr.rst
-rw-r--r-- 1 lilian lilian  11K janv.  6 18:02 ./skulpt.rst
-rw-r--r-- 1 lilian lilian 5,5K janv.  6 18:02 ./sparkline.rst
-rw-r--r-- 1 lilian lilian 3,3K janv.  6 18:02 ./sphinxtabs.en.rst
-rw-r--r-- 1 lilian lilian 3,5K janv.  6 18:02 ./sphinxtabs.fr.rst
-rw-r--r-- 1 lilian lilian 8,3K janv.  6 18:02 ./stats-google-analytics.en.rst
-rw-r--r-- 1 lilian lilian 7,9K janv.  6 18:02 ./stats-google-analytics.fr.rst
-rw-r--r-- 1 lilian lilian  29K janv.  6 18:02 ./sublimetext.en.rst
-rw-r--r-- 1 lilian lilian  32K janv.  6 18:02 ./sublimetext.fr.rst
-rw-r--r-- 1 lilian lilian  14K janv.  6 18:02 ./teaching.en.rst
-rw-r--r-- 1 lilian lilian 2,7K janv.  6 18:02 ./time.rst
-rw-r--r-- 1 lilian lilian 1,5K janv.  6 18:02 ./todo.rst
-rw-r--r-- 1 lilian lilian  17K janv.  6 18:02 ./top10.en.rst
-rw-r--r-- 1 lilian lilian  18K janv.  6 18:02 ./top10.fr.rst
-rw-r--r-- 1 lilian lilian 9,7K janv.  6 18:02 ./trademarks.rst
-rw-r--r-- 1 lilian lilian 8,0K janv.  6 18:02 ./transifex.en.rst
-rw-r--r-- 1 lilian lilian 9,3K janv.  6 18:02 ./transifex.fr.rst
-rw-r--r-- 1 lilian lilian 4,9K janv.  6 18:02 ./try-ocaml.en.rst
-rw-r--r-- 1 lilian lilian 4,8K janv.  6 18:02 ./try-ocaml.fr.rst
-rw-r--r-- 1 lilian lilian  24K janv.  6 18:02 ./tutogit.en.rst
-rw-r--r-- 1 lilian lilian  26K janv.  6 18:02 ./tutogit.fr.rst
-rw-r--r-- 1 lilian lilian  17K janv.  6 18:02 ./visualstudiocode.en.rst
-rw-r--r-- 1 lilian lilian  19K janv.  6 18:02 ./visualstudiocode.fr.rst
-rw-r--r-- 1 lilian lilian 7,8K janv.  6 18:02 ./vpn.fr.rst
-rw-r--r-- 1 lilian lilian  15K janv.  6 18:02 ./wakatime.en.rst
-rw-r--r-- 1 lilian lilian  15K janv.  6 18:02 ./wakatime.fr.rst
-rw-r--r-- 1 lilian lilian  16K janv.  6 18:02 ./what-i-watch-on-youtube.en.rst
-rw-r--r-- 1 lilian lilian 3,7K janv.  6 18:02 ./whatsnew.en.rst
-rw-r--r-- 1 lilian lilian 3,8K janv.  6 18:02 ./whatsnew.fr.rst
-rw-r--r-- 1 lilian lilian 8,9K janv.  6 18:02 ./wolfram.en.rst
-rw-r--r-- 1 lilian lilian 8,9K janv.  6 18:02 ./wolfram.fr.rst
-rw-r--r-- 1 lilian lilian 2,6K janv.  6 18:02 ./zotero.en.rst
-rw-r--r-- 1 lilian lilian 2,7K janv.  6 18:02 ./zotero.fr.rst
-rw-r--r-- 1 lilian lilian  11K janv.  8 19:48 ./a-faire-avant-30-ans.rst
-rw-r--r-- 1 lilian lilian  32K janv.  8 19:48 ./projects.fr.rst
-rw-r--r-- 1 lilian lilian  11K janv. 10 19:47 ./resume-de-mon-annee-2017.rst
-rw-r--r-- 1 lilian lilian  16K janv. 10 19:47 ./resume-de-mon-annee-2018.rst
-rw-r--r-- 1 lilian lilian 2,4K févr.  3 10:59 ./resume-de-mon-annee-2019.rst
-rw-r--r-- 1 lilian lilian 9,5K févr.  6 08:17 ./vieprivee.rst
-rw-r--r-- 1 lilian lilian  12K févr. 11 11:52 ./recherche.fr.rst
-rw-r--r-- 1 lilian lilian  11K févr. 11 11:52 ./research.en.rst

We can look for the 10 longest filenames of the reStructuredText files in the current directory:

$ for i in $(find -iname '*'.rst | sort); do echo "${#i} : $i" | sed s/'^\([0-9]\) '/'0\1 '/; done | sort | tail | awk '{ print $3 }'
./resume-de-mon-annee-2018.rst
./resume-de-mon-annee-2019.rst
./stats-google-analytics.en.rst
./stats-google-analytics.fr.rst
./what-i-watch-on-youtube.en.rst
./what-i-watch-on-youtube.fr.rst
./ce-que-je-regarde-sur-youtube.en.rst
./ce-que-je-regarde-sur-youtube.fr.rst
./data-analysis-of-2-years-of-sms-2016-2017.en.rst
./data-analysis-of-2-years-of-sms-2016-2017.fr.rst

We can also ask GPG to produce (on the fly) a signature of the current file (for more information about GPG, see pgp.html):

$ gpg --quiet -o - --armor --detach-sign runblock.en.rst
-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEEvxBajcdUkbnW7axdAarNucEI+KAFAlxhVH8ACgkQAarNucEI
+KBvWA//SarWigUwCsm22tZ3AGwDH15Fppzz0HzvX745O6bWQr8j+U/B8i2NniU/
d+C1r9rrwe6vNJn/aUxUPfqSepUTMF8Ik+W3wREb0MpCPw9qnRMQ/CASOR4wyde/
XvO4Q5qKaPfW5TDyYqejoL/xf8O+RMufvwcSbBwdfIQhwod9xMK3Qm/SXX+X3f88
qw3NRz6V0G8G920cKrvh0HaGdhimxmIxjL0gycvHeiC32x4MxV0EnE3MQQevvgOj
LB7DKO2ok2R7PJj0geW5iVQLrkkOwzBJaA/HJ1+s8te7ZkhlLkwuNvoUDATCBdG5
U19p5Po485B7fiHNHUYYCMDcJsa9mo240S1pEqeSn2/WXIyXmnjhPBLS3v7PLcJr
QxFOar2jOUREg5ZAfsvp0EQj+2ADBFgAaa7oyMQ4kk1uVLOKaTyOF03/h9f+icws
bJjPOsNRHl9fst9ICmt9l0lnNAinR/8V1tGmNsHFj8/YsAZ7PQhVADhacRjKxxnh
1r+OM5bqngFIkJaME7Cnsaki2rPjP5iR5x5PE+ybnDt+iXRgAkYGlN4z8GHmZlo7
4AlkSIN1bVZx+xHauzoO7yDWMqRP16fcRfBwtrthgwiENvNQg5dpWPvPL/TqwWRF
igT1SIDjDHID5+qV6sp9ogqS6heD/r25AEU6YbBNg9odRoX6Vw4=
=dJ7/
-----END PGP SIGNATURE-----

Other examples

figlet can print text in a nice « ASCII art » form:

$ figlet "Isn't  it  pretty  ?"
 ___           _ _      _ _                     _   _            ___ 
|_ _|___ _ __ ( ) |_   (_) |_    _ __  _ __ ___| |_| |_ _   _   |__ \
 | |/ __| '_ \|/| __|  | | __|  | '_ \| '__/ _ \ __| __| | | |    / /
 | |\__ \ | | | | |_   | | |_   | |_) | | |  __/ |_| |_| |_| |   |_| 
|___|___/_| |_|  \__|  |_|\__|  | .__/|_|  \___|\__|\__|\__, |   (_) 
                                |_|                     |___/        

My script bin/series.sh was conceived to automatically play the next episode for your current TV show, and it uses a ~/current file to know which folder to use. We can use it to display the TV show I am currently watching:

$ echo -e "These days, I am watching the TV show : $(basename "$(cat /home/lilian/current | tr _ ' ')") :)"
These days, I am watching the TV show : Young Sheldon :)

Current state of the git repository (shows which files are new (N), modified (M) or deleted (D)) :

$ git status --porcelain
?? todo_01-01-2020.sh

A stupid example with an elk:

$ cowthink -W 160 -f /usr/share/cowsay/cows/moose.cow "And you think this is funny?"
 ______________________________
( And you think this is funny? )
 ------------------------------
  o
   o   \_\_    _/_/
    o      \__/
           (oo)\_______
           (__)\       )\/\
               ||----w |
               ||     ||

We can go crazy, and try to display a picture in ASCII text :

$ convert ~/.link.ico jpg:- | jp2a -b - --size=31x20
+-------------------------------+
|MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM|
|MMMMMMMMMMWNNNNNNNNWMMMMMMMMMMM|
|MMMMMMMMMNk'.......ONNWMMMMMMMM|
|MMMMMMMWNc.;::;cxl;'..xWMMMMMMM|
|MMMMMWKl',;;lkkxc,'oxd;'dXXNMMM|
|MMMMNd.'::;.'::;.c0Ox:.   .lWMM|
|MMMN;.:cc..dl. .xOko; ....xNMMM|
|MMMWd,;:c..kkc. ;;'. .okkKWMMMM|
|MMMMMXc,;..x00, .l0.'Oc..'XMMMM|
|MMMMMMW0: .dO0,.k00,,kkkc'KMMMM|
|MMMMMMMMW: ,ck'.xkkxo;;;dNWMMMM|
|MMMMMMMMW; ..;. ,;;;' lMMMMMMMM|
|MMMMMMW0d,.:, .,,. .. lMMMMMMMM|
|MMMMMMWl 'cc, l0Kc :: lMMMMMMMM|
|MMMMMMMo .,,. ;oo, ll lMMMMMMMM|
|MMMMMMWO:. ',,,,,. .. lMMMMMMMM|
|MMMMMMNko. ;ccccc'    ;ONMMMMMM|
|MMMMMMNdcllodddxxxkOO0KKNMMMMMM|
|MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM|
+-------------------------------+

The same, even bigger (fyi, this image is the favicon of this website):

$ convert ~/.link.ico jpg:- | jp2a -b - --size=62x30
+--------------------------------------------------------------+
|MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMMMMMMMMWXKKKKKKKKKKKKKKKNMMMMMMMMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMMMMMMWNO,...............xMMMMMMMMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMMMMMKoc:'........';;,'.'cdddddOWMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMN0Ox:...;cclooooodxkxc,;,'...':xO0XWMMMMMMMMMMMM|
|MMMMMMMMMMMMWNl.  .;cccclx00000klc;.  c0000Ko.  :KWWMWWMMMMMMM|
|MMMMMMMMMMWOc,'''';:c:'.'cdddddc'.':lok00kdd:   .:ccc:c0MMMMMM|
|MMMMMMMMWKx;..,ccc:;;,...,;;;;;'..,xK00OOo;;'        ..dWMMMMM|
|MMMMMMMNd..';;:ccc,. .okx;     ,dkO000xll,.         :0XNMMMMMM|
|MMMMMMMXc. 'cccccc'  .dKOc''.  .ldo:;,'...  ;xkkkkkkKWMMMMMMMM|
|MMMMMMMMWOc;,,:ccc'  .dK0xdo,  ..,,,,'.  .';lddddxOXWMMMMMMMMM|
|MMMMMMMMMMW0:.'ccc'  .dK0000c     .dKO;  ;O0d.    .:KMMMMMMMMM|
|MMMMMMMMMMMMNkc;,..  .dK0000c  .cloOKO;  ;O0koll:. 'OMMMMMMMMM|
|MMMMMMMMMMMMMMNKk;.  .oOkO00c  ,kK000Oc..:xkkkxkd;.,OMMMMMMMMM|
|MMMMMMMMMMMMMMMMWNd. .;c:dO0:  'x0OOO0kkkoc:;...,xXXWMMMMMMMMM|
|MMMMMMMMMMMMMMMMMWd.  ...;ol,  .:ooooooll;..,x000NMMMMMMMMMMMM|
|MMMMMMMMMMMMMMMMMNo.  ...',,.  .',,,,,,,,.  '0MMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMWWWNo. .,c:.                  '0MMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMWx,,,'',;:c:.  'oooddl.  .,,.  '0MMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMWl   .;cccc:.  ;O0K0Kx'  ;xx;  'OMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMo.  .,::::;.  ;kOOOOd.  cOO:  'OMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMo    ......   .......   ,ol,  .OMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMWk;;;.   .'''''''''',.   .,,.  'OWWMMMMMMMMMMMMMM|
|MMMMMMMMMMMMWNK00Oc. .cxxddddddddxl.        .xXNWMMMMMMMMMMMMM|
|MMMMMMMMMMMMNO;....   ........'''''..',,,;;:cldkKWMMMMMMMMMMMM|
|MMMMMMMMMMMMMNkoddxxkkkO000000KKKKXXXNNNNWWWMMMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM|
|MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM|
+--------------------------------------------------------------+

A few statistics about this git repository:

$ echo "Number of commits per author (on this git repository) :"
$ git --no-pager shortlog -sn --all
Number of commits per author (on this git repository) :
  1724	Lilian Besson
     5	Lilian Besson (Naereen)
     1	Jill-Jênn Vie

A small calendar, showing in ASCII the active days in this git repository (with this other script, note that this web-page is a nice looking version of this ASCII « calendar »):

$ git-cal --ascii
      Feb   Mar       Apr     May     Jun       Jul     Aug     Sep       Oct     Nov     Dec       Jan     Feb 
            .         . .         .   .                                       .       .             .       .   
    M                   .       .     . .         .         . O                 .   .       .               . . 
                .   .   .                           .   .     .                 .       .     o     O           
    W     .               .     0     .     .                           .         .                   .     .   
            .     .     .                           .                       .     . .               .           
    F             . 0 .                     .                       .             o .                           
                    o .             .   .     .                                       .                         

                                                                                          Less   . o O 0  More
  97: Total commits
   5: Days ( Apr 13 2018 - Apr 17 2018 ) - Longest streak excluding weekends       
   5: Days ( Apr 13 2018 - Apr 17 2018 ) - Longest streak including weekends       
   1: Days ( Feb 11 2019 - Feb 11 2019 ) - Current streak                          

Adding support for another language: OCaml?

In the Sphinx configuration file, conf.py, we can easily add shortcuts to use this runblock extension with other languages.

First, we have to create an empty dictionary called autorun_languages:

autorun_languages = {}

Then, add a value truc (which has to be a valid command-line program, like gnuplot or ocaml) and truc_prefix_chars (size of the prefix) to enable a new directive .. code-block:: truc in all your reStructuredText document (in this project only):

# Add these two lines in your 'conf.py' file
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 now works

With this trick, we can now include example of code snippet in 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;;
39916800
        OCaml version 4.04.2

Pour plus de détails, cf. le code source de l’extension autorun.py.


A weird bug of pygments

This runblock extension uses the great pygments Python library to color the code.

Sometimes, I have seen the pygments or pygmentize command-line tool break completely, and the only bugfix I found was to manually delete the « experimental » support of pkg_resources in the pygments file plugin.py, by manually forcing pkg_resources = None (at line 41). It’s durty, but it fixes my bug…