README

******************************************************************
  ``sphinxcontrib-texfigure`` -- TeX Figure extension for Sphinx
******************************************************************

Overview
========

``sphinxcontrib-texfigure`` is a Sphinx_ extension for generating
figures and diagrams from TeX files.

For an example of a diagram this extension could produce, please see
http://htsql.org/doc/overview.html#htsql-in-a-nutshell.  For more
examples, see ``demo`` directory in the source distribution.

This extension is similar in scope to `sphinxcontrib-tikz`_ extension,
but with different approach to input and options.

This software is written by Kirill Simonov (`Prometheus Research, LLC`_)
and released under BSD license.


Prerequisites
=============

The following executables are used for rasterizing TeX documents:

* ``pdflatex``
* ``pdftoppm``
* ``pnmcrop``
* ``pnmtopng``

On a Debian_ or a `Debian-derived`_ system, they could be installed
with::

    # apt-get install texlive
    # apt-get install poppler-utils
    # apt-get install netpbm

If you want to generate diagrams with TikZ_, install::

    # apt-get install texlive-pictures


Usage
=====

To enable this extension, add the following line to ``conf.py``::

    extensions.append('sphinxcontrib.texfigure')

Use ``texfigure`` directive to convert a TeX/LaTeX document to an image.
For example::

    .. texfigure:: hello-world.tex

This directive will render *Hello, World!* in a box assuming that
``hello-world.tex`` contains the following LaTeX document::

       \documentclass{article}
       \usepackage{tikz}
       \pagestyle{empty}

       \begin{document}
       \begin{tikzpicture}
       \node[draw] {Hello, World!};
       \end{tikzpicture}
       \end{document}

Use option ``align`` to specify horizontal alignment, ``alt`` to specify
text content of the image::

    .. texfigure:: hello-world.tex
       :align: center
       :alt: Hello, World!


Reference
=========

Directives
----------

``texfigure``
    Renders a figure from a TeX document.

    The parameter of the directive must be the path to a TeX/LaTeX file.
    This directive has no body.

    Options:

    ``align``
        Horizontal alignment (``left``, ``center``, or ``right``)
    ``alt``
        Alternative text content of the image.

Configuration parameters
------------------------

``texfigure_pdftex`` (default: ``pdflatex``)
    Path to ``pdftex`` or ``pdflatex`` executable.

``texfigure_pdftoppm`` (default: ``pdftoppm``)
    Path to ``pdftoppm`` executable.

``texfigure_pnmcrop`` (default: ``pnmcrop``)
    Path to ``pnmcrop`` executable.

``texfigure_pnmtopng`` (default: ``pnmtopng``)
    Path to ``pnmtopng`` executable.

``texfigure_texinputs`` (default: ``[]``)
    List of directories where TeX searches for input files.

``texfigure_resolution`` (default: ``110``)
    Image resolution, in DPI.

CSS classes
-----------

``texfigure``
    Applies to the generated image.


.. _Sphinx: http://sphinx-doc.org/
.. _sphinxcontrib-tikz: https://pypi.python.org/pypi/sphinxcontrib-tikz
.. _Prometheus Research, LLC: http://prometheusresearch.com/
.. _Debian: http://debian.org/
.. _Debian-derived: http://ubuntu.com/
.. _TikZ: http://www.texample.net/tikz/

.. vim: set spell spelllang=en textwidth=72: