Browse Source

Add a lot of doc

pull/71/head
Florian Mounier 12 years ago
parent
commit
b01dedcedd
  1. 259
      pages/basic_customizations.rst
  2. 206
      pages/builtin_styles.rst
  3. 35
      pages/chart_types.rst
  4. 116
      pages/custom_styles.rst
  5. 8
      pages/documentation.rst
  6. 2
      pages/first_steps.rst
  7. 20
      pages/home.rst
  8. 3
      pages/interpolations.rst
  9. 6
      pages/metadata.rst
  10. 8
      pages/other_customizations.rst
  11. 174
      pages/parametric_styles.rst
  12. 80
      pages/sparks.rst
  13. 196
      pages/styles.rst
  14. 78
      pages/web.rst

259
pages/basic_customizations.rst

@ -30,7 +30,7 @@ pygal is customized with the help of the `Config` class (see `config.py <https:/
By instanciating it
^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~
Just import the `Config` class and instanciate it:
@ -48,7 +48,7 @@ Just import the `Config` class and instanciate it:
...
By inheriting it
^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~
Import the `Config` class and override it:
@ -68,7 +68,7 @@ Import the `Config` class and override it:
Using keyword args
^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~
As a shorthand for a one shot config, you can specify all config arguments as keyword args:
@ -96,6 +96,33 @@ It indicates the desired size of the svg.
You can also set `explicit_size` to True to add size attributes to the svg tag.
Spacing
-------
``spacing, margin``
Spacing determines the space between all elements:
.. pygal-code::
chart = pygal.Bar(spacing=50)
chart.x_labels = u'αβγδ'
chart.add('line 1', [5, 15, 10, 8])
chart.add('line 2', [15, 20, 8, 11])
Margin is the external chart margin:
.. pygal-code::
chart = pygal.Bar(margin=50)
chart.x_labels = u'αβγδ'
chart.add('line 1', [5, 15, 10, 8])
chart.add('line 2', [15, 20, 8, 11])
Scaling
-------
@ -132,8 +159,11 @@ Finaly you can tell at which precision pygal should stop scaling (in log10):
Title
-----
Titles
------
Chart title
~~~~~~~~~~~
``title``
@ -145,25 +175,49 @@ You can add a title to the chart by setting the `title` option:
chart.add('line', [.0002, .0005, .00035])
Two y axes
----------
X title
~~~~~~~
``secondary``
``x_title``
You can plot your values to 2 separate axes, thanks to `wiktorn <https://github.com/wiktorn>`_
You can add a title to the x axis by setting the `x_title` option:
.. pygal-code::
chart = pygal.Line(title=u'Some different points')
chart = pygal.Line(title=u'Some points', x_title='X Axis')
chart.add('line', [.0002, .0005, .00035])
Y title
~~~~~~~
``y_title``
You can add a title to the y axis by setting the `y_title` option:
.. pygal-code::
chart = pygal.Line(title=u'Some points', y_title='Y Axis')
chart.add('line', [.0002, .0005, .00035])
Font size
~~~~~~~~~
``title_font_size``
.. pygal-code::
chart = pygal.Line(title=u'Some points', x_title='X Axis', y_title='Y Axis',
title_font_size=24)
chart.add('line', [.0002, .0005, .00035])
chart.add('other line', [1000, 2000, 7000], secondary=True)
Labels
------
Add labels
^^^^^^^^^^
~~~~~~~~~~
``x_labels, y_labels``
@ -177,8 +231,21 @@ You can specify x labels and y labels, depending on the graph type:
chart.add('line', [.0002, .0005, .00035])
Remove y labels
~~~~~~~~~~~~~~~
``show_y_labels``
Set this to False to deactivate y labels:
.. pygal-code::
chart = pygal.Line(show_y_labels=False)
chart.add('line', [.0002, .0005, .00035])
Rotate labels
^^^^^^^^^^^^^
~~~~~~~~~~~~~
``x_label_rotation, y_label_rotation``
@ -188,19 +255,27 @@ 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.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.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])
Change minor/major labels
^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~
``x_labels_major, x_labels_major_every, x_labels_major_count, show_minor_x_labels``
@ -209,7 +284,11 @@ You can alter major minor behaviour for the abscissa thanks to `Arjen Stolk <htt
.. 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.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.x_labels_major = ['This is the first point !', 'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
@ -217,46 +296,99 @@ You can alter major minor behaviour for the abscissa thanks to `Arjen Stolk <htt
.. pygal-code::
chart = pygal.Line(x_label_rotation=20, x_labels_major_every=3)
chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !']
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, x_labels_major_count=3)
chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !']
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, show_minor_x_labels=False)
chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !']
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.x_labels_major = ['This is the first point !', 'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
Display
-------
Font size
~~~~~~~~~
``label_font_size, major_label_font_size``
.. pygal-code::
``show_legend, show dots``
chart = pygal.Line(x_label_rotation=20, label_font_size=8, major_label_font_size=12)
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.x_labels_major = ['This is the first point !', 'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
Dots
----
Removing
~~~~~~~~
``show_dots``
You can remove dots by setting `show_dots` at `False`
You can remove legend and dots by setting these at `False`
.. pygal-code::
chart = pygal.Line(show_legend=False)
chart = pygal.Line(show_dots=False)
chart.add('line', [.0002, .0005, .00035])
Size
~~~~
``dots_size``
.. pygal-code::
chart = pygal.Line(show_dots=False)
chart = pygal.Line(dots_size=5)
chart.add('line', [.0002, .0005, .00035])
Legends
-------
Removing
~~~~~~~~
``show_legend``
You can remove legend by setting these at `False`
.. pygal-code::
chart = pygal.Line(show_legend=False)
chart.add('line', [.0002, .0005, .00035])
Legend at bottom
----------------
~~~~~~~~~~~~~~~~
``legend_at_bottom``
@ -269,6 +401,68 @@ You can put legend at bottom by setting `legend_at_bottom` at True:
chart.add('line', [.0002, .0005, .00035])
Legend box size
~~~~~~~~~~~~~~~
``legend_box_size``
.. pygal-code::
chart = pygal.Line(legend_box_size=18)
chart.add('line', [.0002, .0005, .00035])
Font size
~~~~~~~~~
``legend_font_size``
.. pygal-code::
chart = pygal.Line(legend_font_size=20)
chart.add('line', [.0002, .0005, .00035])
Tooltip
-------
Rounded corner
~~~~~~~~~~~~~~
``tooltip_border_radius``
.. pygal-code::
chart = pygal.Line(tooltip_border_radius=10)
chart.add('line', [.0002, .0005, .00035])
Font size
~~~~~~~~~
``tooltip_font_size``
.. pygal-code::
chart = pygal.Line(tooltip_font_size=24)
chart.add('line', [.0002, .0005, .00035])
Two y axes
----------
``secondary``
You can plot your values to 2 separate axes, thanks to `wiktorn <https://github.com/wiktorn>`_
.. pygal-code::
chart = pygal.Line(title=u'Some different points')
chart.add('line', [.0002, .0005, .00035])
chart.add('other line', [1000, 2000, 7000], secondary=True)
Rendering
---------
@ -299,7 +493,7 @@ To fill to an other reference than zero:
Font sizes
----------
``label_font_size, value_font_size, tooltip_font_size, title_font_size, legend_font_size``
``value_font_size, tooltip_font_size``
Set the various font size
@ -323,7 +517,11 @@ You can override that by setting truncation lenght with `truncate_legend` and `t
.. pygal-code::
chart = pygal.Line(truncate_legend=3, truncate_label=17)
chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !']
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])
@ -361,3 +559,6 @@ Text to display instead of the graph when no data is supplied:
chart = pygal.Line(no_data_text='No result found')
chart.add('line', [])
Next: `Interpolations </interpolations>`_

206
pages/builtin_styles.rst

@ -0,0 +1,206 @@
===============
Documentation
===============
Built-in Styles
===============
pygal provides 14 built-in styles:
.. contents::
Default
-------
.. pygal-code::
chart = pygal.StackedLine(fill=True, interpolate='cubic')
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Neon
----
.. pygal-code::
from pygal.style import NeonStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=NeonStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Dark Solarized
--------------
.. pygal-code::
from pygal.style import DarkSolarizedStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkSolarizedStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Light Solarized
---------------
.. pygal-code::
from pygal.style import LightSolarizedStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightSolarizedStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Light
-----
.. pygal-code::
from pygal.style import LightStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Clean
-----
.. pygal-code::
from pygal.style import CleanStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=CleanStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Red Blue
--------
.. pygal-code::
from pygal.style import RedBlueStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=RedBlueStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Dark Colorized
--------------
.. pygal-code::
from pygal.style import DarkColorizedStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkColorizedStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Light Colorized
---------------
.. pygal-code::
from pygal.style import LightColorizedStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightColorizedStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Turquoise
---------
.. pygal-code::
from pygal.style import TurquoiseStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=TurquoiseStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Light green
-----------
.. pygal-code::
from pygal.style import LightGreenStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightGreenStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Dark green
----------
.. pygal-code::
from pygal.style import DarkGreenStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkGreenStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Dark green blue
---------------
.. pygal-code::
from pygal.style import DarkGreenBlueStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkGreenBlueStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Blue
----
.. pygal-code::
from pygal.style import BlueStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=BlueStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])

35
pages/chart_types.rst

@ -14,7 +14,7 @@ Line charts
-----------
Basic
^^^^^
~~~~~
Basic simple line graph:
@ -29,7 +29,7 @@ Basic simple line graph:
line_chart.add('Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4, 8.9, 5.8, 6.7, 6.8, 7.5])
Stacked
^^^^^^^
~~~~~~~
Same graph but with stacked values and filled rendering:
@ -48,7 +48,7 @@ Bar charts / Histograms
-----------------------
Basic
^^^^^
~~~~~
Basic simple bar graph:
@ -64,7 +64,7 @@ Basic simple bar graph:
Stacked
^^^^^^^
~~~~~~~
Same graph but with stacked values:
@ -80,7 +80,7 @@ Same graph but with stacked values:
Horizontal
^^^^^^^^^^
~~~~~~~~~~
Horizontal bar diagram:
@ -99,7 +99,7 @@ XY charts
---------
Basic
^^^^^
~~~~~
Basic XY lines, drawing cosinus:
@ -117,7 +117,7 @@ Basic XY lines, drawing cosinus:
Scatter Plot
^^^^^^^^^^^^
~~~~~~~~~~~~
Disabling stroke make a good scatter plot
@ -131,7 +131,7 @@ Disabling stroke make a good scatter plot
DateY
^^^^^
~~~~~
You can index values by dates (Thanks to `Snarkturne <https://github.com/snarkturne>`_)
.. pygal-code::
@ -151,7 +151,7 @@ Pies
----
Basic
^^^^^
~~~~~
Simple pie:
@ -168,7 +168,7 @@ Simple pie:
Multi-series pie
^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~
Same pie but divided in sub category:
@ -187,7 +187,7 @@ Radar charts
------------
Basic
^^^^^
~~~~~
Simple Kiviat diagram:
@ -206,7 +206,7 @@ Dot charts
----------
Basic
^^^^^
~~~~~
Punch card like chart:
@ -225,7 +225,7 @@ Funnel charts
-------------
Basic
^^^^^
~~~~~
Funnel chart:
@ -243,7 +243,7 @@ Gauge charts
------------
Basic
^^^^^
~~~~~
Simple gauge chart:
@ -263,7 +263,7 @@ Pyramid charts
--------------
Basic
^^^^^
~~~~~
Population pyramid:
@ -294,7 +294,7 @@ Worldmap charts
---------------
Basic
^^^^^
~~~~~
Highlight some countries:
@ -524,3 +524,6 @@ The following countries are supported:
- `za`: South Africa
- `zm`: Zambia
- `zw`: Zimbabwe
Next: `Styles </styles>`_

116
pages/custom_styles.rst

@ -0,0 +1,116 @@
===============
Documentation
===============
Custom Styles
=============
pygal provides 2 ways to customize styles:
.. contents::
Using Style class
-----------------
You can instantiate the `Style` class with some customizations for quick styling:
.. pygal-code::
from pygal.style import Style
custom_style = Style(
background='transparent',
plot_background='transparent',
foreground='#53E89B',
foreground_light='#53A0E8',
foreground_dark='#630C0D',
opacity='.6',
opacity_hover='.9',
transition='400ms ease-in',
colors=('#E853A0', '#E8537A', '#E95355', '#E87653', '#E89B53'))
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=custom_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Using a custom css
------------------
You can also specify a file containing a custom css for more customization. The css option is an array containing included css by default (except from ``base.css`` which is always included).
It supports local file names and external stylesheet too, just append your URI in the list.
(See the `default css <https://github.com/Kozea/pygal/blob/master/pygal/css/>`_)
NB: Now the css rules are prefixed by an unique id, to prevent collisions when including several svg dirctly into a web page. You can disable it with the `no_prefix` option.
.. pygal-code::
from tempfile import NamedTemporaryFile
custom_css = '''
{{ id }}text {
fill: green;
font-family: monospace;
}
{{ id }}.legends .legend text {
font-size: {{ font_sizes.legend }};
}
{{ id }}.axis {
stroke: #666;
}
{{ id }}.axis text {
font-size: {{ font_sizes.label }};
font-family: sans;
stroke: none;
}
{{ id }}.axis.y text {
text-anchor: end;
}
{{ id }}#tooltip text {
font-size: {{ font_sizes.tooltip }};
}
{{ id }}.dot {
fill: yellow;
}
{{ id }}.color-0 {
stroke: #ff1100;
fill: #ff1100;
}
{{ id }}.color-1 {
stroke: #ffee00;
fill: #ffee00;
}
{{ id }}.color-2 {
stroke: #66bb44;
fill: #66bb44;
}
{{ id }}.color-3 {
stroke: #88bbdd;
fill: #88bbdd;
}
{{ id }}.color-4 {
stroke: #0000ff;
fill: #0000ff;
}
'''
custom_css_file = '/tmp/pygal_custom_style.css'
with open(custom_css_file, 'w') as f:
f.write(custom_css)
config = pygal.Config(fill=True, interpolate='cubic')
config.css.append(custom_css_file)
chart = pygal.StackedLine(config)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Next: `Basic customizations </basic_customizations>`_

8
pages/documentation.rst

@ -11,11 +11,7 @@ User documentation
- `Styles </styles>`_ - change the style.
- `Basic customizations </basic_customizations>`_ - start to improve your charts.
- `Interpolations </interpolations>`_ - smooth your lines.
- `Sparklines </sparks>`_ - create simple sparklines.
- `Metadata </metadata>`_ - enrich your graph.
- `Other customizations </other_customizations>`_ - customize all the things.
Developer documentation
=======================
- `Create a chart type </chart_creation>`_ - extend pygal.
- `Embedding in a web page </web>`_ - see several ways to use pygal on the intertubes.

2
pages/first_steps.rst

@ -64,3 +64,5 @@ And finally add a title and some labels:
bar_chart.add('Fibonacci', [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55])
bar_chart.add('Padovan', [1, 1, 1, 2, 2, 3, 4, 5, 7, 9, 12])
Next: `Charts types </chart_types>`_

20
pages/home.rst

@ -64,24 +64,26 @@ It features various graph types:
Python/Css styling with some packaged themes (`default </styles/#default>`_,
`light </styles/#light>`_,
`neon </styles/#neon>`_,
`clean </styles/#clean>`_,
`dark_solarized </styles/#dark-solarized>`_,
`light_solarized </styles/#light-solarized>`_)
Python/Css styling with some pre-defined themes. See `styling </styles/>`_.
`And a lot of options to customize the charts. </basic_customizations>`_
And a lot of options to `customize the charts. </basic_customizations>`_
Get it !
========
- `Get the package on pypi <http://pypi.python.org/pypi/pygal/>`_
- `Fork me on github <http://github.com/Kozea/pygal>`_
- Get the package on `pypi <http://pypi.python.org/pypi/pygal/>`_
- Fork me on `github <http://github.com/Kozea/pygal>`_
More information in the `download page </download>`_
Get started
===========
Start `here </first_steps/>`_ to make your first steps.
Technical Description
=====================

3
pages/interpolations.rst

@ -74,3 +74,6 @@ You can change the resolution of the interpolation with the help of `interpolati
chart = pygal.Line(interpolate='krogh', interpolation_precision=50)
chart.add('line', [1, 5, 17, 12, 5, 10])
Next: `Sparklines </sparklines>`_

6
pages/metadata.rst

@ -28,7 +28,7 @@ Links
-----
Basic
^^^^^
~~~~~
You can also add hyper links:
@ -58,7 +58,7 @@ You can also add hyper links:
Advanced
^^^^^^^^
~~~~~~~~
You can specify a dictionary to xlink with all links attributes:
@ -96,4 +96,4 @@ You can specify a dictionary to xlink with all links attributes:
}])
Next: `Other customizations </other_customizations>`_

8
pages/other_customizations.rst

@ -112,3 +112,11 @@ this option disables the xml prolog in the output.
Since no encoding is declared, the result will be in unicode instead of bytes.
No prefix
---------
``no_prefix``
Normally pygal set an unique id to the chart and use it to style each chart to avoid collisions when svg are directly embedded in html. This can be a problem if you use external styling overriding the prefixed css. You can set this to True in order to prevent that behaviour.

174
pages/parametric_styles.rst

@ -0,0 +1,174 @@
===============
Documentation
===============
Parametric Styles
=================
pygal provides 5 parametric styles:
.. contents::
Usage
-----
A parametric style is initiated with a default color and the other are generated from this one:
.. pygal-code::
from pygal.style import LightenStyle
dark_lighten_style = LightenStyle('#336676')
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
You can set the `step` parameter to tell between how much colors the color modifier will be applied
.. pygal-code::
from pygal.style import LightenStyle
dark_lighten_style = LightenStyle('#336676', step=5)
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
and the `max_` to limit the amplitude at a certain value (in % for all color operation except rotate which is 360):
.. pygal-code::
from pygal.style import LightenStyle
dark_lighten_style = LightenStyle('#336676', step=5, max_=10)
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
You can tell the style to inheritate all the styles from another theme:
.. pygal-code::
from pygal.style import LightenStyle, LightColorizedStyle
dark_lighten_style = LightenStyle('#336676', base_style=LightColorizedStyle)
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
And you can manually set the properties just like any other theme:
.. pygal-code::
from pygal.style import LightenStyle, LightColorizedStyle
dark_lighten_style = LightenStyle('#336676', base_style=LightColorizedStyle)
dark_lighten_style.background = '#ffcccc'
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Styles
------
Rotate
~~~~~~
.. pygal-code::
from pygal.style import RotateStyle
dark_rotate_style = RotateStyle('#9e6ffe')
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_rotate_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
.. pygal-code::
from pygal.style import RotateStyle, LightColorizedStyle
dark_rotate_style = RotateStyle('#75ff98', base_style=LightColorizedStyle)
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_rotate_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Lighten
~~~~~~~
.. pygal-code::
from pygal.style import LightenStyle
dark_lighten_style = LightenStyle('#004466')
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Darken
~~~~~~
.. pygal-code::
from pygal.style import DarkenStyle
darken_style = DarkenStyle('#ff8723')
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=darken_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Saturate
~~~~~~~~
.. pygal-code::
from pygal.style import SaturateStyle
saturate_style = SaturateStyle('#609f86')
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=saturate_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Desaturate
~~~~~~~~~~
.. pygal-code::
from pygal.style import DesaturateStyle
desaturate_style = DesaturateStyle('#8322dd')
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=desaturate_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])

80
pages/sparks.rst

@ -0,0 +1,80 @@
===============
Documentation
===============
Sparklines
==========
pygal provides a simple way to get beautiful sparklines.
.. contents::
Basic
-----
.. pygal-code:: True
chart = pygal.Line()
chart.add('', [1, 3, 5, 16, 13, 3, 7])
chart.render_sparkline()
Styles
------
It supports styling like any chart but the option is given to the `render_sparkline` method:
.. pygal-code:: sparkline
from pygal.style import DarkSolarizedStyle
chart = pygal.Line()
chart.add('', [1, 3, 5, 16, 13, 3, 7])
chart.render_sparkline(style=DarkSolarizedStyle)
Options
-------
It's the same for other options:
.. pygal-code:: sparkline
chart = pygal.Line()
chart.add('', [1, 3, 5, 16, 13, 3, 7])
chart.render_sparkline(interpolate='cubic')
.. pygal-code:: sparkline
chart = pygal.Line()
chart.add('', [1, 3, 5, 16, 13, 3, 7, 9, 2, 1, 4, 9, 12, 10, 12, 16, 14, 12, 7, 2])
chart.render_sparkline(width=500, height=25, show_dots=True)
Sparktext
---------
If you want to get a simple spartext, use the render_sparktext function:
.. code-block:: python
chart = pygal.Line()
chart.add('', [1, 3, 5, 16, 13, 3, 7])
chart.render_sparktext()
 `▁▁▂█▆▁▃`
You can also specify an explicit minimum for the values:
.. code-block:: python
chart = pygal.Line()
chart.add('', [1, 3, 5, 16, 13, 3, 7])
chart.render_sparktext(relative_to=0)
 `▁▂▃█▆▂▄`
Next: `Metadata </metadata>`_

196
pages/styles.rst

@ -2,196 +2,8 @@
Documentation
===============
There are three ways to style the charts:
Styles
======
pygal provides 6 different styles and 2 ways to add your own:
.. contents::
Default
-------
.. pygal-code::
chart = pygal.StackedLine(fill=True, interpolate='cubic')
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Neon
----
.. pygal-code::
from pygal.style import NeonStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=NeonStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Dark Solarized
--------------
.. pygal-code::
from pygal.style import DarkSolarizedStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkSolarizedStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Light Solarized
---------------
.. pygal-code::
from pygal.style import LightSolarizedStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightSolarizedStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Light
-----
.. pygal-code::
from pygal.style import LightStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Clean
-----
.. pygal-code::
from pygal.style import CleanStyle
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=CleanStyle)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Custom
------
You can customize styles in two ways:
Using Style class
^^^^^^^^^^^^^^^^^
You can instantiate the `Style` class with some customizations for quick styling:
.. pygal-code::
from pygal.style import Style
custom_style = Style(
background='transparent',
plot_background='transparent',
foreground='#53E89B',
foreground_light='#53A0E8',
foreground_dark='#630C0D',
opacity='.6',
opacity_hover='.9',
transition='400ms ease-in',
colors=('#E853A0', '#E8537A', '#E95355', '#E87653', '#E89B53'))
chart = pygal.StackedLine(fill=True, interpolate='cubic', style=custom_style)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
Using a custom css
^^^^^^^^^^^^^^^^^^
You can also specify a file containing a custom css for more customization. The css option is an array containing included css by default (except from ``base.css`` which is always included).
It supports local file names and external stylesheet too, just append your URI in the list.
(See the `default css <https://github.com/Kozea/pygal/blob/master/pygal/css/>`_)
.. pygal-code::
from tempfile import NamedTemporaryFile
custom_css = '''
text {
fill: green;
font-family: monospace;
}
.legends .legend text {
font-size: {{ font_sizes.legend }};
}
.axis {
stroke: #666;
}
.axis text {
font-size: {{ font_sizes.label }};
font-family: sans;
stroke: none;
}
.axis.y text {
text-anchor: end;
}
#tooltip text {
font-size: {{ font_sizes.tooltip }};
}
.dot {
fill: yellow;
}
.color-0 {
stroke: #ff1100;
fill: #ff1100;
}
.color-1 {
stroke: #ffee00;
fill: #ffee00;
}
.color-2 {
stroke: #66bb44;
fill: #66bb44;
}
.color-3 {
stroke: #88bbdd;
fill: #88bbdd;
}
.color-4 {
stroke: #0000ff;
fill: #0000ff;
}
'''
custom_css_file = '/tmp/pygal_custom_style.css'
with open(custom_css_file, 'w') as f:
f.write(custom_css)
config = pygal.Config(fill=True, interpolate='cubic')
config.css.append(custom_css_file)
chart = pygal.StackedLine(config)
chart.add('A', [1, 3, 5, 16, 13, 3, 7])
chart.add('B', [5, 2, 3, 2, 5, 7, 17])
chart.add('C', [6, 10, 9, 7, 3, 1, 0])
chart.add('D', [2, 3, 5, 9, 12, 9, 5])
chart.add('E', [7, 4, 2, 1, 2, 10, 0])
- Using `built-in themes </builtin_styles>`_
- Using `parametric themes </parametric_styles>`_
- Using `custom themes </custom_styles>`_

78
pages/web.rst

@ -0,0 +1,78 @@
===============
Documentation
===============
Embedding in a web page
=======================
.. contents::
Within an embed tag
-------------------
First setup an url entry point for you svg: `/mysvg.svg` don't forget to set the mime-type to `image/svg+xml`. (If you are using flask you can use the `render_response` method.)
Then in your html put an embed tag like this:
.. code-block:: html
<!DOCTYPE html>
<html>
<head>
<!-- ... -->
</head>
<body>
<figure>
<embed type="image/svg+xml" src="/mysvg.svg" />
</figure>
</body>
</html>
You can also use an iframe tag, but automatic sizing with `width: 100%` will not work.
Directly in the html
--------------------
You can insert it directly in a html page with the use of `disable_xml_declaration`.
You have to put the javascript manually in you webpage, for instance:
.. code-block:: html
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript" src="http://kozea.github.com/pygal.js/javascripts/svg.jquery.js"></script>
<script type="text/javascript" src="http://kozea.github.com/pygal.js/javascripts/pygal-tooltips.js"></script>
<!-- ... -->
</head>
<body>
<figure>
<!-- Pygal render() result: -->
<svg
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://www.w3.org/2000/svg"
id="chart-e6700c90-7a2b-4602-961c-83ccf5e59204"
class="pygal-chart"
viewBox="0 0 800 600">
<!--Generated with pygal 1.0.0 ©Kozea 2011-2013 on 2013-06-25-->
<!--http://pygal.org-->
<!--http://github.com/Kozea/pygal-->
<defs>
<!-- ... -->
</defs>
<title>Pygal</title>
<g class="graph bar-graph vertical">
<!-- ... -->
</g>
</svg>
<!-- End of Pygal render() result: -->
</figure>
</body>
</html>
You can use `explicit_size` to set the svg size from the `width`, `height` properties.
Loading…
Cancel
Save