ANSI-Colored Terminal Output for Sphinx

erbsland-sphinx-ansi is a lightweight Sphinx extension that renders ANSI-colored and formatted terminal output directly in your documentation.

It is especially useful when documenting command-line tools, build logs, or interactive sessions where color improves readability and realism.

Features

Optional escape-char parameter that allows you to replace the ANSI escape character (\x1b) with a visible placeholder character inside reStructuredText sources.
Optional theme parameter that allows you to customize the CSS class prefix used for styling.
Works with both HTML and non-HTML output formats.

Quick Start

Installation

Install the package from PyPI:

pip install erbsland-sphinx-ansi

Configuration

Enable the extension in your conf.py:

extensions = [
    # ...
    "erbsland.sphinx.ansi",
]

No additional configuration is required.

Usage

To render ANSI-colored output, use the erbsland-ansi directive:

.. erbsland-ansi::
    :escape-char: ␛

    ␛[32m[sphinx-autobuild] ␛[36mStarting initial build␛[0m
    ␛[32m[sphinx-autobuild] ␛[34m> python -m sphinx build doc _build␛[0m
    ␛[32m[sphinx-autobuild] ␛[36mServing on http://127.0.0.1:9000␛[0m
    ␛[32m[sphinx-autobuild] ␛[36mWaiting to detect changes...␛[0m

The :escape-char: option defines which character in the source file represents the ANSI escape character. This makes the escape sequences visible and editable in your documentation sources.

If the option is omitted, the directive expects real ANSI escape sequences.

Rendered Example

The following block demonstrates the rendered output:

[sphinx-autobuild] Starting initial build
[sphinx-autobuild] > python -m sphinx build doc _build
[sphinx-autobuild] Serving on http://127.0.0.1:9000
[sphinx-autobuild] Waiting to detect changes...

When building HTML documentation, the ANSI color codes are converted into styled output that closely resembles the original terminal appearance.

Custom Theming

Use the parameter theme to customize the CSS class prefix used for styling:

.. erbsland-ansi::
    :escape-char: ␛
    :theme: my-theme

    ␛[32m[sphinx-autobuild] ␛[36mStarting initial build␛[0m
    ␛[32m[sphinx-autobuild] ␛[34m> python -m sphinx build doc _build␛[0m
    ␛[32m[sphinx-autobuild] ␛[36mServing on http://127.0.0.1:9000␛[0m
    ␛[32m[sphinx-autobuild] ␛[36mWaiting to detect changes...␛[0m

Create a CSS file static/my-theme.css with the following content:

.my-theme-block {
    background-color: #fdfbff;
    color: #23143a;
}

.my-theme-bold { font-weight: bold; }
.my-theme-dim { opacity: 0.5; }
.my-theme-italic { font-style: italic; }
.my-theme-underline { text-decoration: underline; }
.my-theme-blink { text-decoration: blink; }
.my-theme-reverse { }
.my-theme-hidden { opacity: 0; }
.my-theme-strike { text-decoration: line-through; }
.my-theme-black { color: #2f153f; }
.my-theme-red { color: #c0213a; }
.my-theme-green { color: #1b8a3a; }
.my-theme-yellow { color: #b26a00; }
.my-theme-blue { color: #1c5fd4; }
.my-theme-magenta { color: #9a1f9b; }
.my-theme-cyan { color: #007e9c; }
.my-theme-white { color: #3a234e; }
.my-theme-black.my-theme-bold, .my-theme-bright-black { color: #16001f; }
.my-theme-red.my-theme-bold, .my-theme-bright-red { color: #a80023; }
.my-theme-green.my-theme-bold, .my-theme-bright-green { color: #0b6b2a; }
.my-theme-yellow.my-theme-bold, .my-theme-bright-yellow { color: #8f4b00; }
.my-theme-blue.my-theme-bold, .my-theme-bright-blue { color: #0c49b8; }
.my-theme-magenta.my-theme-bold, .my-theme-bright-magenta { color: #7d0082; }
.my-theme-cyan.my-theme-bold, .my-theme-bright-cyan { color: #006682; }
.my-theme-white.my-theme-bold, .my-theme-bright-white { color: #210e33; }
.my-theme-background-black { background-color: #f0e7ff; }
.my-theme-background-red { background-color: #ffd9de; }
.my-theme-background-green { background-color: #d6f5dd; }
.my-theme-background-yellow { background-color: #ffe9bf; }
.my-theme-background-blue { background-color: #dbe7ff; }
.my-theme-background-magenta { background-color: #f5dcff; }
.my-theme-background-cyan { background-color: #d6f6ff; }
.my-theme-background-white { background-color: #efe3ff; }
.my-theme-background-bright-black { color: #16001f; }
.my-theme-background-bright-red { color: #a80023; }
.my-theme-background-bright-green { color: #0b6b2a; }
.my-theme-background-bright-yellow { color: #8f4b00; }
.my-theme-background-bright-blue { color: #0c49b8; }
.my-theme-background-bright-magenta { color: #7d0082; }
.my-theme-background-bright-cyan { color: #006682; }
.my-theme-background-bright-white { color: #210e33; }

Output with the custom theme:

[sphinx-autobuild] Starting initial build
[sphinx-autobuild] > python -m sphinx build doc _build
[sphinx-autobuild] Serving on http://127.0.0.1:9000
[sphinx-autobuild] Waiting to detect changes...