| author: | Leandro Lucarella <llucax@gmail.com> |
|---|
This extension allows embedded ASCII art to be rendered as nice looking images using aafigure.
aafigure is a program and a reStructuredText directive to allow embedded ASCII art figures to be rendered as nice images in various image formats. The aafigure directive needs a hardcoded image format, so it doesn’t goes well with Sphinx multi-format support.
This extension adds the aafig directive that automatically selects the image format to use acording to the Sphinx writer used to generate the documentation.
You can see the latest documentation at the sphinxcontrib-aafig website or download it in PDF format.
This source:
.. aafig::
:aspect: 60
:scale: 150
:proportional:
:textual:
+-------+ +-----------+
| Hello +-------->+ aafigure! |
+-------+ +-----------+
is rendered as:
You can see all the available versions at PyPI.
aafigure should be installed in the system for this extension to work. Alternatively you can download it to any folder and add that folder to the Python’s path through the Sphinx conf.py file, for example:
import sys, os
sys.path.extend(os.path.abspath('path/to/aafigure')])
Unpack the archive, enter the sphinxcontrib-aafig-x.y directory and run:
python setup.py install
You can always use the original reStructuredText aafigure extension, but choosing a hardcoded format can be a bad idea when using Sphinx, because PDF might not be suitable for HTML and PNG can look ugly in a PDF document.
This extension uses the same aafigure code to add a more Sphinxy directive called aafig. This directive accepts the same options as the original aafigure directive (please, see aafigure documentation for more information). There are some differences though:
For an example on using the aafig directive see the Quick Example.
A few configuration options are added (all optional, of course ;) to Sphinx so you can set them in the conf.py file:
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.
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=1.5, aspect=0.5, proportional=True)
Note that in this case the aspec and scale options are specified as floats, as originally done by aafigure. See aafigure documentation for a complete list of options and their defaults.
This file describes user-visible changes between the extension versions.
I don't like licenses, because I don't like having to worry about all this
legal stuff just for a simple piece of software I don't really mind anyone
using. But I also believe that it's important that people share and give back;
so I'm placing this work under the following license.
BOLA - Buena Onda License Agreement (v1.0)
------------------------------------------
This work is provided 'as-is', without any express or implied warranty. In no
event will the authors be held liable for any damages arising from the use of
this work.
To all effects and purposes, this work is to be considered Public Domain.
However, if you want to be "buena onda", you should:
1. Not take credit for it, and give proper recognition to the authors.
2. Share your modifications, so everybody benefits from them.
3. Do something nice for the authors.
4. Help someone who needs it.
5. Don't waste. Anything, but specially energy that comes from natural
non-renewable resources.
6. Be tolerant. Everything that's good in nature comes from cooperation.