===============
 Documentation
===============


Basic customizations
====================


.. contents::


How to customize:
-----------------

pygal is customized with the help of the config class (see `config.py <https://github.com/Kozea/pygal/blob/master/pygal/config.py>`_). It can be changed in several ways:

.. pygal::

  from pygal import Config
  config = Config()
  config.show_legend = False
  config.human_readable = True
  config.fill = True
  config.x_scale = config.y_scale = 0.25
  chart = pygal.XY(config)
  from math import cos, sin, pi
  a = 2 * pi / 5.
  chart.add('*', [(cos(i*a+pi/2.), sin(i*a+pi/2.)) for i in (0,2,4,1,3,0)])


By instanciating it
^^^^^^^^^^^^^^^^^^^

Just import the config class and instanciate it:

.. code-block::

  from pygal import Config

  config = Config()
  config.show_legend = False
  config.human_readable = True
  config.fill = True
  config.x_scale = .25
  config.y_scale = .25
  chart = pygal.XY(config)
  ...

By inheriting it
^^^^^^^^^^^^^^^^

Import the config class and override it:

.. code-block::

  from pygal import Config

  class StarConfig(Config):
      show_legend = False
      human_readable = True
      fill = True
      x_scale = .25
      y_scale = .25

  chart = pygal.XY(StarConfig())
  ...


Using keyword args
^^^^^^^^^^^^^^^^^^

As a shorthand for a one shot config you can specify all config argument as keyword args:

.. code-block::

  chart = pygal.XY(show_legend=False, human_readable=True, fill=True, x_scale=.25, y_scale=.25)
  ...


Size
----

`width, height, explicit_size`


The simplest and usefull customizations is the svg size to render.
It indicates the desired size of the svg.


.. pygal-code:: 200 100

  chart = pygal.Bar(width=200, height=100)
  chart.add('1', 1)
  chart.add('2', 2)

You can also set `explicit_size` to True to add size attributes to the svg tag.

Scaling
-------

`x_scale, y_scale, include_x_axis`


Indicate a hint for the scale computation:

.. pygal-code::

  chart = pygal.Line()
  chart.add('line', [.0002, .0005, .00035])

.. pygal-code::

  chart = pygal.Line(y_scale=.0001)
  chart.add('line', [.0002, .0005, .00035])


You may want to always have the absissa in your graph:

.. pygal-code::

  chart = pygal.Line(y_scale=.0001, include_x_axis=True)
  chart.add('line', [.0002, .0005, .00035])


Title
-----

`title`

You can add a title to the chart by setting the title option:

.. pygal-code::

  chart = pygal.Line(title=u'Some points')
  chart.add('line', [.0002, .0005, .00035])


Labels
------

`x_labels, y_labels`

You can specify x labels and y labels, depending on the graph type:

.. pygal-code::

  chart = pygal.Line()
  chart.x_labels = 'Red', 'Blue', 'Green'
  chart.y_labels = .0001, .0003, .0004, .00045, .0005
  chart.add('line', [.0002, .0005, .00035])


Display
-------

`show_legend, show dots`

You can remove legend and dots by setting these at False

.. pygal-code::

  chart = pygal.Line(show_legend=False)
  chart.add('line', [.0002, .0005, .00035])


.. pygal-code::

  chart = pygal.Line(show_dots=False)
  chart.add('line', [.0002, .0005, .00035])

Rendering
---------

`fill, stroke, zero`

You can disable line stroking:

.. pygal-code::

  chart = pygal.Line(stroke=False)
  chart.add('line', [.0002, .0005, .00035])

And enable line filling:

.. pygal-code::

  chart = pygal.Line(fill=True)
  chart.add('line', [.0002, .0005, .00035])

To fill to an other reference than zero:

.. pygal-code::

  chart = pygal.Line(fill=True, zero=.0004)
  chart.add('line', [.0002, .0005, .00035])


Font sizes
----------

`label_font_size, value_font_size, tooltip_font_size, title_font_size, legend_font_size`


Set the various font size

.. pygal-code::

  chart = pygal.Line(label_font_size=34, legend_font_size=8)
  chart.add('line', [0, .0002, .0005, .00035])


Label rotation
--------------

`x_label_rotation, y_label_rotation`


Allow label rotation (in degrees) to avoid axis cluttering:

.. pygal-code::

  chart = pygal.Line()
  chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !']
  chart.add('line', [0, .0002, .0005, .00035])


.. pygal-code::

  chart = pygal.Line(x_label_rotation=20)
  chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !']
  chart.add('line', [0, .0002, .0005, .00035])


Human readable
--------------

`human_readable`


Display values in human readable form:

1 230 000 -> 1.23M
.00 098 7 -> 987µ

.. pygal-code::

  chart = pygal.Line(human_readable=True, y_scale=.0001)
  chart.add('line', [0, .0002, .0005, .00035])


No data text
------------

`no_data_text`


Text to display instead of the graph when no data is supplied:

.. pygal-code::

  chart = pygal.Line()
  chart.add('line', [])

.. pygal-code::

  chart = pygal.Line(no_data_text='No result found')
  chart.add('line', [])