1. dan mackinlay
  2. sphinx-contrib


sphinx-contrib / aafig /

Filename Size Date modified Message
352 B
1.3 KB
47 B
2.9 KB
83 B
1.7 KB
.. -*- restructuredtext -*-

aafigure_ extension for Sphinx

:copyright: Copyright 2009 by Leandro Lucarella <llucax@gmail.com>.
:license: BSD, see LICENSE for details.


This extension allows embeded ASCII art to be rendered as nice looking images
using the **great** aafigure_ reStructuredText_ extension.

.. _aafigure: http://docutils.sourceforge.net/sandbox/aafigure/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html

_aafigure is a program and a reStructuredText_ directive to allow embeded 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.

.. _Sphinx: http://sphinx.pocoo.org/

This extension adds the ``aafig`` directive that automatically selects the
image format to use acording to the Sphinx_ writer used to generate the


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),
except for the ``:format:`` option, which is selected automatically depending
on the Sphinx builder you are using.


A few configuration options are added (all optional):

``aafig_format`` <dict>:
   image format used for the different builders. Only ``latex`` and ``html``
   are supported for now. You can specify the desired format for each builder
   using a dictionary. For example::

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

   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=1.5, aspect=0.5, proportional=True)

    See aafigure_ documentation for a complete list of options and their


* aafigure_ (r5978 or later).
* reportlab_ (for LaTeX/PDF output)
* PIL_ (for any image format other than SVG or PDF)

.. _reportlab: http://www.reportlab.org/
.. _PIL: http://www.pythonware.com/products/pil/

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 ``conf.py``, for example::

    import sys, os