Testing the `autorun` Sphinx extension¶

À faire

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.

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

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

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:

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:

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

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

Other examples¶

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

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:

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

A stupid example with an elk:

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

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

A few statistics about this git repository:

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

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:

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…

Testing the autorun Sphinx extension¶