sphinx-contrib / aafig /

Filename Size Date modified Message
..
sphinxcontrib
519 B
1.3 KB
47 B
2.9 KB
83 B
1.8 KB
.. -*- 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://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
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. 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
    defaults.


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

* 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

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

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.