sphinxcontrib-asciiart

http://packages.python.org/sphinxcontrib-asciiart

A Sphinx extension, which turns ascii art color sequences in Sphinx documents into colored HTML or .png or other output.

Installation

This extension can be installed from the Python Package Index:

pip install sphinxcontrib-asciiart

Usage

Just add sphinxcontrib.asciiart to the list of extensions in the conf.py file. For example:

extensions = ['sphinxcontrib.asciiart']

And then use the asciiart block to include your ascii art code:

.. asciiart::
    :line-height: 1.0em
    :spacing: 0

    [31m                                              :. ,..[0m
    [31m                                            .' :~.':_.,[0m
    [31m                                          .'   ::.::'.'[0m
    [31m                                         :     ::'  .:[0m
    [31m                                       `.:    .:  .:/[0m
    [31m                                        `::--.:'.::'[0m
    [31m                                          |. _:===-'[0m
    [32m                                        / /[0m
    [32m                       ,---.---.    __,','[0m
    [32m                      (~`.  \   )   )','.,---..[0m
    [32m                       `v`\ | ,' .-'.:,'_____   `.[0m
    [32m                           )|/.-~.--~~--.   ~~~-. \[0m
    [32m                         _/-'_.-~        ""---.._`.|[0m
    [32m                    _.-~~_.-~                    ""'[0m
    [32m             _..--~~_.(~~[0m
    [32m  __...---~~~_..--~~[0m
    [32m'___...---~~~[0m

Then it would be rendered as a colorful literal block or image. To show the content of the pypi webpage, I remove the colors:

                                              :. ,..
                                            .' :~.':_.,
                                          .'   ::.::'.'
                                         :     ::'  .:
                                       `.:    .:  .:/
                                        `::--.:'.::'
                                          |. _:===-'
                                         / /
                        ,---.---.    __,','
                       (~`.  \   )   )','.,---..
                        `v`\ | ,' .-'.:,'_____   `.
                            )|/.-~.--~~--.   ~~~-. \
                          _/-'_.-~        ""---.._`.|
                     _.-~~_.-~                    ""'
              _..--~~_.(~~
   __...---~~~_..--~~
,'___...---~~~

Options

sphinxcontrib-asciiart provide rich options to custimize the output. You can configure the global setting, you also can change the behavior for only one ascii art literal block.

When the global setting and literal block based setting are change, or if the content of the literal block is changed, it would re-build the target image even there is target image cache already.

global setting

First of all, you should configure the sphinxcontrib-asciiart in the conf.py to enable the sphinxcontrib-asciiart:

extensions = ['sphinxcontrib-asciiart']

ascii_art_output_format: We use the suffix to control the build output format for different target. The default value is as below and you can change it in your conf.py in the following format:
```
ascii_art_output_format = dict(html='.html', latex='.png', text='.txt')
```

Besides the .png, we support many other kinds of image output format:

bmp dib eps gif icns ico im jpg jpeg msp pcx png ppm sgi spider tga tiff
webp xbm palm pdf xv bufr fits grib hdf5 mpeg

ascii_art_image_font: When we render the image instead of “.html” and “.txt”, which font name we use, It’s a list of font name that we want to use to render the ascii art. The front one have high priority to be used. the default is:
```
ascii_art_image_font = 'NSimSun, simsun, monospace'
```
ascii_art_image_fontsize: When we render the image instead of “.html” and “.txt”, the font size we want to use, it’s an integer, the default value is:
```
ascii_art_image_fontsize = 14
```

block specific setting

‘spacing’: int, The space between each lines. The default value is -1.
‘font’: str, A list of font name that we want to use to render the ascii art. The front one have high priority to be used.
‘fontsize’: int, The font size we want to use to render the ascii art.
‘include’: Use the content of the file given in include as ascii content.
‘textwidth’: The maxmium seen character number in each lines. Lines longer than that would case line break. Default is 0 and 0 means never line break.
‘leadingspace’: When textwidth option is given, then the wrapped text would start at leadingspace.

For example:

.. asciiart::
    :font: simsun, monospace, "Times new roman"
    :fontsize: 14
    :spacing: 0

    .· .·.   [1;35m/╲     /|[0m
            ·[1;35m│  \  ╱ |[0m
       [1;35m\-.___ / \  \/ / /[0m
        [1;35m\ __ ╲  [1;33m.,.[1;35m| ╱__[0m
        [1;35m╱  乁  [1;33m'\|)[1;35m╱￣  ╲[0m
    [1;35m-＜`︶╲__╱ [1;33m︶[1;35m╲    ╲ \[0m
        [35m￣￣ /   /  ╱﹀乀 \│[0m
             [1;35m╲  ' /[1;30m╲  ·╲/[0m
               [1;35m\| /   [1;30m\  ; ｀[0m
                [1;35m\/     [1;30m\  ·,[0m
    .----/[1;35m      ′      [1;30m︳  ·__,[0m

Changelog

1.0.0 Initial upload.
1.1.2 Support new options: textwidth, include

Metadata

Release files for sphinxcontrib-asciiart 1.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sphinxcontrib-asciiart 1.1.3
File	Size	Uploaded
sphinxcontrib_asciiart-1.1.3.tar.gz	12.5 kB	Nov 14, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for sphinxcontrib-asciiart 1.1.3
File	Interpreter	ABI	Platform	Reset
sphinxcontrib_asciiart-1.1.3-py3-none-any.whl 10.9 kB Nov 14, 2025	Python 3	none	any	Details

Total release size: 23.4 kB

Release files / sphinxcontrib_asciiart-1.1.3.tar.gz

Download URL	sphinxcontrib_asciiart-1.1.3.tar.gz
Size	12.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`0913c14f1983698e5269ab29dbe71b24b3cf5c7688cb5f4d3af8fcf2d0e990e1`
BLAKE2b-256 checksum How to use checksums	`c38c7d11ed22963ee046ff7ffa4484e6ce0c4b03b00233a45269f4e4b7742694`
Upload date	Nov 14, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Release files / sphinxcontrib_asciiart-1.1.3-py3-none-any.whl

Download URL	sphinxcontrib_asciiart-1.1.3-py3-none-any.whl
Size	10.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`61d615610e8982249e145fd93921d73b82b8b2962a7a26f53236308e41347167`
BLAKE2b-256 checksum How to use checksums	`4199c187d84062893dde27394f1303bef354b0f99d2686a6a00208cae552fd11`
Upload date	Nov 14, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`