ERBSLAND SPHINX ANSI

A lightweight Sphinx extension for rendering colored ANSI terminal formatting in docs

Language Python

Framework Sphinx

License Apache 2.0

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

It is especially useful for command-line tools, build logs, and interactive terminal sessions where preserving color and formatting improves clarity and makes examples feel realistic.

Installation and Quick Example

Install the package from PyPI:

pip install erbsland-sphinx-ansi

Enable the extension in your conf.py:

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

Use the erbsland-ansi directive in your reStructuredText source:

.. erbsland-ansi::
    :escape-char: #

    #[32m[sphinx-autobuild] #[36mStarting initial build#[0m
    #[32m[sphinx-autobuild] #[34m> python -m sphinx build doc _build#[0m

The :escape-char: option is optional. If you omit it, the directive expects real ANSI escape sequences in the content.

Key Features

This extension focuses on one clear purpose and keeps the implementation simple:

Render ANSI-colored and formatted terminal output directly in Sphinx content.
Provide an optional escape-char to keep ANSI sequences readable and easy to edit in source files.
Support an optional theme parameter to customize the CSS class prefix used for styling.
Work with both HTML and non-HTML output formats.

For HTML builds, ANSI sequences are converted into styled output. For non-HTML formats, formatting is stripped automatically and plain text is preserved.

Ready to Add ANSI Output to Your Docs?

Set up the extension in just a few minutes and render terminal output in your documentation exactly as users see it.

Open the Quick Start

Requirements

The runtime requirements are intentionally minimal:

Python 3.10 or newer
Sphinx 8.0 or newer

For development, the project requires Python 3.12 or newer and additional dependencies listed in requirements-dev.txt, including pytest, hatch, and hatch-vcs.

Custom Theming

You can customize the generated CSS class prefix with the theme option:

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

This allows you to integrate ANSI-rendered output cleanly into your existing Sphinx theme and style guidelines.

Sources and License

The complete source code for Erbsland Sphinx ANSI is available on GitHub. The project is released under the Apache License 2.0.

Sources on GitHub

Documentation