1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
========
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:
.. aafig::
:aspect: 60
:scale: 150
:proportional:
:textual:
+-------+ +-----------+
| Hello +-------->+ aafigure! |
+-------+ +-----------+
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).
.. Links:
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
History
=======
This extension was once shipped separately: `sphinxcontrib-aafig website`__.
__ http://packages.python.org/sphinxcontrib-aafig/
|
