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:
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 setting1
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
andtext
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
andscale
options are specified as floats, as originally done by aafigure.
TODO¶
- Add color validation for
fill
,background
andforeground
options. - Add
aa
role for easily embed small images (like arrows).
History¶
This extension was once shipped separately: sphinxcontrib-aafig website.