Question

I am currently using Sphinx to document a mixed-language project, such that the documentation includes examples of interactive sessions not just in Python, but also in bash and the Windows command-line, as well as MATLAB and other interpreters. While Pygments takes care of highlighting everything nicely, all of the interactive sessions I’ve included in the documentation so far show up in HTML output preceded by the Python prompt, >>>. How can I change that prompt to $, for example, when documenting bash sessions?

---

Edited to clarify:

As documented in the Sphinx manual, under “Showing code examples,” ReST source for a Sphinx document can contain code like:

>>> # python code here
>>> print "foo"
foo

This code then gets turned into markup like that demonstrated in the documentation of argparse in the Python standard library documentation, showing the code after the >>> as a highlighted snippet. Though it is clear that one can simply typeset unhighlighted blocks with other prompt characters, I am wondering how to combine a prompt other than >>> with the interactive prompt styling shown in the argparse example.

Answer 1

You can use, say, $ as the prompt for bash snippets, but it cannot be used for Python if you want the output to be nicely highlighted.

>>> is recognized as the interactive Python prompt. But using another prompt won’t work. The documentation says: “Normal Python code is only highlighted if it is parseable”, and something like

$ import sys 

or

>> import sys 

is not parseable as Python.

It is possible to use extensions to make Sphinx accept other Python prompts. The ipython directive is an example (not tested by me).

---

These examples work well for me:

.. code-block:: bash

   $ pwd
   /home
   $ echo TEST
   TEST

.. code-block:: python

   >>> import sys
   >>> print "X"
   X

And the following produces identical formatting and highlighting:

.. highlight:: bash

::

   $ pwd
   /home
   $ echo TEST
   TEST

.. highlight:: python

::

   >>> import sys
   >>> print "X"
   X

For Python interactive sessions, no extra markup is actually needed (unless the most recent .. highlight:: directive has a target other than python). Sphinx recognizes >>> automatically:

>>> import sys
>>> print "X"
X

Without any prompts, the code must be in a code-block (or literal block) to be formatted properly:

.. code-block:: python

   import sys
   print "X"