.. -*- restructuredtext -*-

==============================
aafigure_ extension for Sphinx
==============================

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


About
=====

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

.. _aafigure: http://launchpad.net/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
documentation.


Usage
=====

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.


Configuration
=============

A few configuration options are added (all optional):

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

    See aafigure_ documentation for a complete list of options and their
    defaults.


Requirements
============

* aafigure_ (0.3 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

    sys.path.extend(os.path.abspath('path/to/aafigure')])


TODO
====

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


