Sphinx

This extension adds the aafig directive that automatically selects the image format to use according to the Sphinx writer used to generate the documentation.

Quick Example

This source:

.. aafig::
    :aspect: 60
    :scale: 150
    :proportional:
    :textual:

    +-------+         +-----------+
    | Hello +-------->+ aafigure! |
    +-------+         +-----------+

is rendered as:

_images/aafig-abcc578fb6944d77128eea80590e058578c26492.svg

Enabling the extension in Sphinx

Just add aafigure.sphinxext to the list of extensions in the conf.py file. For example:

extensions = ['aafigure.sphinxext']

Options

The aafig directive has the following options:

  • :scale: <int> enlarge or shrink image

  • :line_width: <float> change line with (SVG only currently)

  • :foreground: <str> foreground color in the form #rgb or #rrggbb

  • :background: <str> background color in the form #rgb or #rrggbb (not for SVG output)

  • :fill: <str> fill color in the form #rgb or #rrggbb

  • :aspect: <int> change aspect ratio. Effectively it is the width of the image that is multiplied by this percentage. The default setting 1 is useful when shapes must have the same look when drawn horizontally or vertically. However, :aspect: 50 looks more like the original ASCII and even smaller factors may be useful for timing diagrams and such. But there is a risk that text is cropped or is draw over an object besides it.

    The stretching is done before drawing arrows or circles, so that they are still good looking.

  • :proportional: use a proportional font instead of a mono-spaced

  • :textual: prefer to detect text instead of fills

  • :rounded: use arcs instead of straight lines for many diagonals

  • :scale: and :aspect: options are specified using percentages (without the % sign), to match the reStructuredText image directive.

Configuration

A few configuration options are added (all optional, of course ;) to Sphinx so you can set them in the conf.py file:

aafig_format <dict>:

image format used for the different builders. All latex, html and text builder are supported, and it should be trivial to add support for other builders if they correctly handle images (and if aafigure can render an image format suitable for that builder) by just adding the correct format mapping here.

A special format None is supported, which means not to use aafigure to render the image, just show the raw ASCII art as is in the resulting document (using a literal block). This is almost only useful for the text builder.

You can specify the format - builder mapping using a dict. For example:

aafig_format = dict(latex='pdf', html='svg', text=None)

These are the actual defaults.

aafig_default_options <dict>:

default aafigure options. These options are used by default unless they are overridden explicitly in the aafig directive. The default aafigure options are used if this is not specified. You can provide partial defaults, for example:

aafig_default_options = dict(scale=150, aspect=50, proportional=True)

Note that in this case the aspec and scale options are specified as floats, as originally done by aafigure.

TODO

  • Add color validation for fill, background and foreground options.
  • Add aa role for easily embed small images (like arrows).

History

This extension was once shipped separately: sphinxcontrib-aafig website.