Table Of Contents

Previous topic

lunar.sphinx.ext.programoutput – Include program output

Next topic

lunar.sphinx.ext.issuetracker – Reference issues in issue trackers

This Page

lunar.sphinx.ext.ansi – Parse ANSI control sequences


As of now, this extension does only work properly, when used with the HTML builder.

Some command line programs use ANSI control sequences to colour their output. This extension provides a directive to include such output into the documentation, and interpret these control sequences in order to colour the output in the documentation, too:

.. ansi-block::

This directive interprets its content as literal block containing ANSI control sequences for coloured output.

If the option string_escape is specified, the content of the directive is decoded using the string_escape codec. Thus you can include Python escape sequences, and therefore use \x1b instead of the real escape character.

Instead of using this directive, it is much more convenient, to enable the lunar.sphinx.ext.programoutput extension, and enable the programoutput_use_ansi setting. Then the output of programs will automatically be colored, if it contains control sequences:

.. command-output:: /bin/echo -e \\x1b\[31mHello world\\x1b\[0m
$ /bin/echo -e \\x1b\[31mHello world\\x1b\[0m
Hello world


The appearance is controlled by html_ansi_stylesheet:


The stylesheet to use for ANSI color sequences. As of now, the following stylesheets are provided:

  • black-on-white.css: Use dark colors on a white background.

If this configuration value is None (the default), no stylesheet is added by the extension. You have to provide your own stylesheet.

If you do not like the builtin stylesheets, set html_ansi_stylesheet to None and create your own stylesheet. This stylesheet must provide styles for the following text format classes:

  • ansi-bold: Bold text
  • ansi-underscore: Underlined text

Moreover these classes, which refer to a colour, must be included:

  • ansi-black: Black colour
  • ansi-red: Red colour
  • ansi-green: Green colour
  • ansi-yellow: Yellow colour
  • ansi-blue: Blue colour
  • ansi-magenta: Magenta colour
  • ansi-cyan: Cyan colour
  • ansi-white: White colour

Put this stylesheet somewhere in your html_static_path and make it known to sphinx by including the following code snippet in your

def setup(app):