Warning
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:
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
:shell:
$ /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:
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:
Moreover these classes, which refer to a colour, must be included:
Put this stylesheet somewhere in your html_static_path and make it known to sphinx by including the following code snippet in your conf.py.
def setup(app):
app.add_stylesheet('my_ansi_theme.css')