.. highlight:: rest
.. default-domain:: rst

:py:mod:`lunar.sphinx.ext.ansi` -- Parse ANSI control sequences
===============================================================

.. py:module:: lunar.sphinx.ext.ansi
   :synopsis:  Parse and interpret ANSI control sequences


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

.. directive:: 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
:py:mod:`lunar.sphinx.ext.programoutput` extension, and enable the
:confval:`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:

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


Appearance
----------

The appearance is controlled by :confval:`html_ansi_stylesheet`:

.. confval:: 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
:confval:`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 :confval:`html_static_path` and make
it known to sphinx by including the following code snippet in your
``conf.py``.

.. code-block:: python

   def setup(app):
       app.add_stylesheet('my_ansi_theme.css')