runblock.en.rst

Testing the autorun Sphinx extension

This autorun (runblock) Sphinx extension seems to be broken with the most recent versions of Sphinx. It is 12/15 years old... I don't have time to fix it, or try runcmd.

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.

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

pycon

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

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

pycon

>>> import sys >>> print(sys.version)

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:

console

$ echo "Date: $(date). Directory: $(pwd)."

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:

console

$ ls -larth ./{,.}*.rst

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

console

$ for i in $(find -iname '*'.rst | sort); do echo "${#i} : $i" | sed s/'^([0-9]) '/'01 '/; done | sort | tail | awk '{ print $3 }'

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

console

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

Other examples

figlet can print text in a nice "ASCII art" form:

console

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

console

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

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

console

$ git status --porcelain

A stupid example with an elk:

console

$ cowthink -W 160 -f /usr/share/cowsay/cows/moose.cow "And you think this is funny?"

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

console

$ convert ~/.link.ico jpg:- | jp2a -b - --size=31x20

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

console

$ convert ~/.link.ico jpg:- | jp2a -b - --size=62x30

A few statistics about this git repository:

console

$ echo "Number of commits per author (on this git repository) :" $ git --no-pager shortlog -sn --all

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

console

$ git-cal --ascii

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:

ocaml

# let rec f = function 0 -> 1 | n -> n *(f (n-1)) in # print_int (f 11);; # Printf.printf "n OCaml version %sn" Sys.ocaml_version;;

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…