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!

.. 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