==========
labella.py
==========

.. image:: https://travis-ci.org/GjjvdBurg/labella.py.svg?branch=master
    :target: https://travis-ci.org/GjjvdBurg/labella.py


Labella.py is a Python 3 clone of `labella.js 
<https://github.com/twitter/labella.js>`_ that supports all the features of 
labella.js and addionally can generate TikZ PDF
images for use in LaTeX.

**Note:** This package is for the most part a direct translation of the 
original `labella.js <https://github.com/twitter/labella.js>`_ code to Python 
3. All the credit for the labella code goes to Krist Wongsuphasawat 
(`@kristw <https://twitter.com/kristw>`_), I only added the code that 
generates PDF output. Labella.py also includes code from 
`d3 <https://github.com/mbostock/d3>`_ for axis scaling, and 
`WebCola <https://github.com/tgdwyer/WebCola>`_ for the VPSC code 
(label placement optimization).

Why?
====
I wrote this for multiple reasons, the most important of which is that I 
wanted to incorporate label graphs like the ones generated by `labella.js 
<https://github.com/twitter/labella.js>`_ in PDF documents, but wasn't 
satisfied with the PDF output generated by SVG-to-PDF converters.  
Additionally, it seemed like a fun way to learn some more Javascript, and 
learn about how `labella.js <https://github.com/twitter/labella.js>`_ works.

Screenshots
===========
These screenshots show the PDF output generated by labella.py (converted to 
.png)

Time scale:

.. image:: https://raw.githubusercontent.com/GjjvdBurg/labella.py/master/examples/timeline_kit_3.png
    :alt: Example of Labella.py output for a timeline
    :width: 100%
    :align: center

Linear scale:

.. image:: https://raw.githubusercontent.com/GjjvdBurg/labella.py/master/examples/timeline_kit_5.png
    :alt: Example of Labella.py output for a timeline
    :width: 100%
    :align: center


Usage
=====
Using labella.py is extremely similar to using 
`labella.js <https://github.com/twitter/labella.js>`_. See the 
`examples <https://github.com/GjjvdBurg/labella.py/tree/master/examples>`_ directory 
for examples of how to use labella.py. These examples are translations of the examples 
included in labella.js and in `d3kit-timeline <https://kristw.github.io/d3kit-timeline/>`_.

For ease of use only the Timeline interface is implemented, which works 
similar to `d3kit-timeline <https://kristw.github.io/d3kit-timeline/>`_. Here is 
a minimal working example for exporting to PDF::

    >>> from labella.scale import LinearScale
    >>> from labella.timeline import TimelineTex
    >>> tl = TimelineTex([
      {'time': 1, 'text': 'Minimal'},
      {'time': 2, 'text': 'Working'},
      {'time': 3, 'text': 'Example'}
      ], options={'scale': LinearScale()})
    >>> tl.export('minimal.tex')

See also the documentation `here <https://github.com/GjjvdBurg/labella.py/tree/master/docs>`_.

Installation
============

Labella.py is available through PyPi, so you can do::

    pip install labella

to install it.

**Note:** Labella.py requires a working LaTeX distribution for both SVG and 
PDF output (see also `the documentation <https://github.com/GjjvdBurg/labella.py/tree/master/docs>`_), 
and has only been tested on Linux. If you run into problems, please open an issue on GitHub.

Author
======

Gertjan van den Burg (`@GjjvdBurg <https://twitter.com/GjjvdBurg>`_).

Licensed under the `Apache License Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.

