From b2f017a87847d8e444a878b6a3e95b15b1b4e180 Mon Sep 17 00:00:00 2001 From: Florian Mounier Date: Wed, 1 Jul 2015 16:23:06 +0200 Subject: [PATCH] Working on porting doc --- docs/Makefile | 3 + docs/basic_customizations.rst | 624 ++++++++++++++++++++++++++ docs/builtin_styles.rst | 206 +++++++++ docs/chart_types.rst | 821 ++++++++++++++++++++++++++++++++++ docs/conf.py | 1 + docs/custom_styles.rst | 116 +++++ docs/documentation.rst | 17 + docs/download.rst | 31 ++ docs/first_steps.rst | 68 +++ docs/index.rst | 111 ++++- docs/interpolations.rst | 120 +++++ docs/metadata.rst | 99 ++++ docs/modules.rst | 7 + docs/other_customizations.rst | 122 +++++ docs/parametric_styles.rst | 174 +++++++ docs/pygal.graph.rst | 190 ++++++++ docs/pygal.rst | 119 +++++ docs/pygal.test.rst | 190 ++++++++ docs/sparks.rst | 80 ++++ docs/styles.rst | 9 + docs/support.rst | 11 + docs/web.rst | 78 ++++ pygal/style.py | 12 + 23 files changed, 3202 insertions(+), 7 deletions(-) create mode 100644 docs/basic_customizations.rst create mode 100644 docs/builtin_styles.rst create mode 100644 docs/chart_types.rst create mode 100644 docs/custom_styles.rst create mode 100644 docs/documentation.rst create mode 100644 docs/download.rst create mode 100644 docs/first_steps.rst create mode 100644 docs/interpolations.rst create mode 100644 docs/metadata.rst create mode 100644 docs/modules.rst create mode 100644 docs/other_customizations.rst create mode 100644 docs/parametric_styles.rst create mode 100644 docs/pygal.graph.rst create mode 100644 docs/pygal.rst create mode 100644 docs/pygal.test.rst create mode 100644 docs/sparks.rst create mode 100644 docs/styles.rst create mode 100644 docs/support.rst create mode 100644 docs/web.rst diff --git a/docs/Makefile b/docs/Makefile index ea91c77..412252b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -190,3 +190,6 @@ pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +rst: + sphinx-apidoc -f -o . ../pygal diff --git a/docs/basic_customizations.rst b/docs/basic_customizations.rst new file mode 100644 index 0000000..8c9c806 --- /dev/null +++ b/docs/basic_customizations.rst @@ -0,0 +1,624 @@ +=============== + Documentation +=============== + + +Basic customizations +==================== + + +.. contents:: + + +How to customize: +----------------- + +pygal is customized with the help of the `Config` class (see `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 arguments 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. + + +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 +------- + +``include_x_axis`` + +Scales are computed automaticaly between the min and the max values. + +You may want to always have the absissa in your graph: + +.. pygal-code:: + + chart = pygal.Line(include_x_axis=True) + chart.add('line', [.0002, .0005, .00035]) + + +``range`` + +You may also want to explicitly set a range, `range` takes a tuple containing min and max: + +.. pygal-code:: + + chart = pygal.Line(range=(.0001, .001)) + chart.add('line', [.0002, .0005, .00035]) + + +``order_min`` + +Finaly you can tell at which precision pygal should stop scaling (in log10): + +.. pygal-code:: + + chart = pygal.Line(order_min=-4) + chart.add('line', [.0002, .0005, .00035]) + + + +Titles +------ + +Chart 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]) + + +X title +~~~~~~~ + +``x_title`` + +You can add a title to the x axis by setting the `x_title` option: + +.. pygal-code:: + + 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]) + + +Labels +------ + +Add 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]) + + +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`` + + +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]) + + +Change minor/major labels +~~~~~~~~~~~~~~~~~~~~~~~~~ + +``x_labels_major, x_labels_major_every, x_labels_major_count, show_minor_x_labels, y_labels_major, y_labels_major_every, y_labels_major_count, show_minor_y_labels`` + +You can alter major minor behaviour of axes thanks to `Arjen Stolk `_ + +.. 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_major = ['This is the first 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_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.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.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_major = ['This is the first point !', 'This is the fourth point !'] + chart.add('line', [0, .0002, .0005, .00035]) + + +.. pygal-code:: + + chart = pygal.Line(y_label_rotation=-20) + chart.y_labels_major = [] + chart.add('line', [0, .0002, .0005, .00035]) + + +.. pygal-code:: + + chart = pygal.Line() + chart.y_labels_major = [.0001, .0004] + chart.add('line', [0, .0002, .0005, .00035]) + + +.. pygal-code:: + + chart = pygal.Line(y_label_rotation=20, y_labels_major_every=3) + chart.add('line', [0, .0002, .0005, .00035]) + + +.. pygal-code:: + + chart = pygal.Line(y_labels_major_count=3) + chart.add('line', [0, .0002, .0005, .00035]) + + +.. pygal-code:: + + chart = pygal.Line(y_labels_major_every=2, show_minor_y_labels=False) + chart.add('line', [0, .0002, .0005, .00035]) + + +Font size +~~~~~~~~~ + +``label_font_size, major_label_font_size`` + +.. pygal-code:: + + 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` + + +.. pygal-code:: + + chart = pygal.Line(show_dots=False) + chart.add('line', [.0002, .0005, .00035]) + + +``show_only_major_dots`` + +You can remove minor x-labelled dots by setting `show_only_major_dots` at `True` + +.. pygal-code:: + + chart = pygal.Line(show_only_major_dots=True) + chart.add('line', range(12)) + chart.x_labels = map(str, range(12)) + chart.x_labels_major = ['2', '4', '8', '11'] + + +Size +~~~~ + +``dots_size`` + +.. pygal-code:: + + 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`` + +You can put legend at bottom by setting `legend_at_bottom` at True: + + +.. pygal-code:: + + chart = pygal.Line(legend_at_bottom=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]) + +Precision +~~~~~~~~~ + +``value_formatter`` + +You can specifiy how the values are displayed on the tooltip using a lambda function. +The code below shows the values to 2 decimal places. + +.. pygal-code:: + + chart = pygal.Line(range=(0, 5)) + chart.add('line', [.070106781, 1.414213562, 3.141592654]) + chart.value_formatter = lambda x: "%.2f" % x + +The datey graph shows the tooltip as "x=? y=?", where the x format is the same as the x_label_format, and the y format is specified via the value_formatter. + +Two y axes +---------- + +``secondary`` + +You can plot your values to 2 separate axes, thanks to `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 +--------- + +``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 +---------- + +``value_font_size, tooltip_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]) + + +Text truncation +--------------- + +``truncate_legend, truncate_label`` + +By default long text are automatically truncated at reasonable length which fit in the graph. + +You can override that by setting truncation lenght with `truncate_legend` and `truncate_label`. + + +.. 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.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', []) + + +Next: `Interpolations `_ diff --git a/docs/builtin_styles.rst b/docs/builtin_styles.rst new file mode 100644 index 0000000..ad9fa98 --- /dev/null +++ b/docs/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]) diff --git a/docs/chart_types.rst b/docs/chart_types.rst new file mode 100644 index 0000000..bfb6bd3 --- /dev/null +++ b/docs/chart_types.rst @@ -0,0 +1,821 @@ +=============== + Documentation +=============== + + +Chart types +=========== + +pygal provides 10 kinds of charts: + +.. contents:: + +Line charts +----------- + +Basic +~~~~~ + +Basic simple line graph: + +.. pygal-code:: + + line_chart = pygal.Line() + line_chart.title = 'Browser usage evolution (in %)' + line_chart.x_labels = map(str, range(2002, 2013)) + line_chart.add('Firefox', [None, None, 0, 16.6, 25, 31, 36.4, 45.5, 46.3, 42.8, 37.1]) + line_chart.add('Chrome', [None, None, None, None, None, None, 0, 3.9, 10.8, 23.8, 35.3]) + line_chart.add('IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6, 54.7, 44.8, 36.2, 26.6, 20.1]) + 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: + +.. pygal-code:: + + line_chart = pygal.StackedLine(fill=True) + line_chart.title = 'Browser usage evolution (in %)' + line_chart.x_labels = map(str, range(2002, 2013)) + line_chart.add('Firefox', [None, None, 0, 16.6, 25, 31, 36.4, 45.5, 46.3, 42.8, 37.1]) + line_chart.add('Chrome', [None, None, None, None, None, None, 0, 3.9, 10.8, 23.8, 35.3]) + line_chart.add('IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6, 54.7, 44.8, 36.2, 26.6, 20.1]) + 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]) + + +Bar charts / Histograms +----------------------- + +Basic +~~~~~ + +Basic simple bar graph: + +.. pygal-code:: + + line_chart = pygal.Bar() + line_chart.title = 'Browser usage evolution (in %)' + line_chart.x_labels = map(str, range(2002, 2013)) + line_chart.add('Firefox', [None, None, 0, 16.6, 25, 31, 36.4, 45.5, 46.3, 42.8, 37.1]) + line_chart.add('Chrome', [None, None, None, None, None, None, 0, 3.9, 10.8, 23.8, 35.3]) + line_chart.add('IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6, 54.7, 44.8, 36.2, 26.6, 20.1]) + 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: + +.. pygal-code:: + + line_chart = pygal.StackedBar() + line_chart.title = 'Browser usage evolution (in %)' + line_chart.x_labels = map(str, range(2002, 2013)) + line_chart.add('Firefox', [None, None, 0, 16.6, 25, 31, 36.4, 45.5, 46.3, 42.8, 37.1]) + line_chart.add('Chrome', [None, None, None, None, None, None, 0, 3.9, 10.8, 23.8, 35.3]) + line_chart.add('IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6, 54.7, 44.8, 36.2, 26.6, 20.1]) + 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]) + + +Horizontal +~~~~~~~~~~ + +Horizontal bar diagram: + +.. pygal-code:: + + line_chart = pygal.HorizontalBar() + line_chart.title = 'Browser usage in February 2012 (in %)' + line_chart.add('IE', 19.5) + line_chart.add('Firefox', 36.6) + line_chart.add('Chrome', 36.3) + line_chart.add('Safari', 4.5) + line_chart.add('Opera', 2.3) + + +XY charts +--------- + +Basic +~~~~~ + +Basic XY lines, drawing cosinus: + +.. pygal-code:: + + from math import cos + xy_chart = pygal.XY() + xy_chart.title = 'XY Cosinus' + xy_chart.add('x = cos(y)', [(cos(x / 10.), x / 10.) for x in range(-50, 50, 5)]) + xy_chart.add('y = cos(x)', [(x / 10., cos(x / 10.)) for x in range(-50, 50, 5)]) + xy_chart.add('x = 1', [(1, -5), (1, 5)]) + xy_chart.add('x = -1', [(-1, -5), (-1, 5)]) + xy_chart.add('y = 1', [(-5, 1), (5, 1)]) + xy_chart.add('y = -1', [(-5, -1), (5, -1)]) + + +Scatter Plot +~~~~~~~~~~~~ + +Disabling stroke make a good scatter plot + +.. pygal-code:: + + xy_chart = pygal.XY(stroke=False) + xy_chart.title = 'Correlation' + xy_chart.add('A', [(0, 0), (.1, .2), (.3, .1), (.5, 1), (.8, .6), (1, 1.08), (1.3, 1.1), (2, 3.23), (2.43, 2)]) + xy_chart.add('B', [(.1, .15), (.12, .23), (.4, .3), (.6, .4), (.21, .21), (.5, .3), (.6, .8), (.7, .8)]) + xy_chart.add('C', [(.05, .01), (.13, .02), (1.5, 1.7), (1.52, 1.6), (1.8, 1.63), (1.5, 1.82), (1.7, 1.23), (2.1, 2.23), (2.3, 1.98)]) + + +DateY +~~~~~ +You can index values by dates (Thanks to `Snarkturne `_) + +.. pygal-code:: + + from datetime import datetime, timedelta + datey = pygal.DateY(x_label_rotation=20) + datey.add("Visits", [ + (datetime(2013, 1, 2), 300), + (datetime(2013, 1, 12), 412), + (datetime(2013, 2, 2), 823), + (datetime(2013, 2, 22), 672) + ]) + +The x axis and tool tip x labels can be specified using `x_label_format`. This uses the formatting string for strftime from `here `_ + +The x labels can also be specified, using an array of datetime objects. + +.. pygal-code:: + + from datetime import datetime, timedelta + datey = pygal.DateY(x_label_rotation=20) + datey.add("Visits", [ + (datetime(2013, 1, 2), 300), + (datetime(2013, 1, 12), 412), + (datetime(2013, 2, 2), 823), + (datetime(2013, 2, 22), 672) + ]) + datey.x_label_format = "%Y-%m-%d" + datey.x_labels = [ + datetime(2013, 1, 1), + datetime(2013, 2, 1), + datetime(2013, 3, 1) + ] + +Pies +---- + +Basic +~~~~~ + +Simple pie: + + +.. pygal-code:: + + pie_chart = pygal.Pie() + pie_chart.title = 'Browser usage in February 2012 (in %)' + pie_chart.add('IE', 19.5) + pie_chart.add('Firefox', 36.6) + pie_chart.add('Chrome', 36.3) + pie_chart.add('Safari', 4.5) + pie_chart.add('Opera', 2.3) + + +Multi-series pie +~~~~~~~~~~~~~~~~ + +Same pie but divided in sub category: + +.. pygal-code:: + + pie_chart = pygal.Pie() + pie_chart.title = 'Browser usage by version in February 2012 (in %)' + pie_chart.add('IE', [5.7, 10.2, 2.6, 1]) + pie_chart.add('Firefox', [.6, 16.8, 7.4, 2.2, 1.2, 1, 1, 1.1, 4.3, 1]) + pie_chart.add('Chrome', [.3, .9, 17.1, 15.3, .6, .5, 1.6]) + pie_chart.add('Safari', [4.4, .1]) + pie_chart.add('Opera', [.1, 1.6, .1, .5]) + + +Radar charts +------------ + +Basic +~~~~~ + +Simple Kiviat diagram: + +.. pygal-code:: + + radar_chart = pygal.Radar() + radar_chart.title = 'V8 benchmark results' + radar_chart.x_labels = ['Richards', 'DeltaBlue', 'Crypto', 'RayTrace', 'EarleyBoyer', 'RegExp', 'Splay', 'NavierStokes'] + radar_chart.add('Chrome', [6395, 8212, 7520, 7218, 12464, 1660, 2123, 8607]) + radar_chart.add('Firefox', [7473, 8099, 11700, 2651, 6361, 1044, 3797, 9450]) + radar_chart.add('Opera', [3472, 2933, 4203, 5229, 5810, 1828, 9013, 4669]) + radar_chart.add('IE', [43, 41, 59, 79, 144, 136, 34, 102]) + + +Box plot +-------- + +Basic +~~~~~ + +Here's some whiskers: + +.. pygal-code:: + + box_plot = pygal.Box() + box_plot.title = 'V8 benchmark results' + box_plot.add('Chrome', [6395, 8212, 7520, 7218, 12464, 1660, 2123, 8607]) + box_plot.add('Firefox', [7473, 8099, 11700, 2651, 6361, 1044, 3797, 9450]) + box_plot.add('Opera', [3472, 2933, 4203, 5229, 5810, 1828, 9013, 4669]) + box_plot.add('IE', [43, 41, 59, 79, 144, 136, 34, 102]) + + +Dot charts +---------- + +Basic +~~~~~ + +Punch card like chart: + +.. pygal-code:: + + dot_chart = pygal.Dot(x_label_rotation=30) + dot_chart.title = 'V8 benchmark results' + dot_chart.x_labels = ['Richards', 'DeltaBlue', 'Crypto', 'RayTrace', 'EarleyBoyer', 'RegExp', 'Splay', 'NavierStokes'] + dot_chart.add('Chrome', [6395, 8212, 7520, 7218, 12464, 1660, 2123, 8607]) + dot_chart.add('Firefox', [7473, 8099, 11700, 2651, 6361, 1044, 3797, 9450]) + dot_chart.add('Opera', [3472, 2933, 4203, 5229, 5810, 1828, 9013, 4669]) + dot_chart.add('IE', [43, 41, 59, 79, 144, 136, 34, 102]) + + +Funnel charts +------------- + +Basic +~~~~~ + +Funnel chart: + +.. pygal-code:: + + funnel_chart = pygal.Funnel() + funnel_chart.title = 'V8 benchmark results' + funnel_chart.x_labels = ['Richards', 'DeltaBlue', 'Crypto', 'RayTrace', 'EarleyBoyer', 'RegExp', 'Splay', 'NavierStokes'] + funnel_chart.add('Opera', [3472, 2933, 4203, 5229, 5810, 1828, 9013, 4669]) + funnel_chart.add('Firefox', [7473, 8099, 11700, 2651, 6361, 1044, 3797, 9450]) + funnel_chart.add('Chrome', [6395, 8212, 7520, 7218, 12464, 1660, 2123, 8607]) + + +Gauge charts +------------ + +Basic +~~~~~ + +Simple gauge chart: + +.. pygal-code:: + + gauge_chart = pygal.Gauge(human_readable=True) + gauge_chart.title = 'DeltaBlue V8 benchmark results' + gauge_chart.x_labels = ['Richards', 'DeltaBlue', 'Crypto', 'RayTrace', 'EarleyBoyer', 'RegExp', 'Splay', 'NavierStokes'] + gauge_chart.range = [0, 10000] + gauge_chart.add('Chrome', 8212) + gauge_chart.add('Firefox', 8099) + gauge_chart.add('Opera', 2933) + gauge_chart.add('IE', 41) + + +Pyramid charts +-------------- + +Basic +~~~~~ + +Population pyramid: + +.. pygal-code:: 600 600 + + ages = [(364381, 358443, 360172, 345848, 334895, 326914, 323053, 312576, 302015, 301277, 309874, 318295, 323396, 332736, 330759, 335267, 345096, 352685, 368067, 381521, 380145, 378724, 388045, 382303, 373469, 365184, 342869, 316928, 285137, 273553, 250861, 221358, 195884, 179321, 171010, 162594, 152221, 148843, 143013, 135887, 125824, 121493, 115913, 113738, 105612, 99596, 91609, 83917, 75688, 69538, 62999, 58864, 54593, 48818, 44739, 41096, 39169, 36321, 34284, 32330, 31437, 30661, 31332, 30334, 23600, 21999, 20187, 19075, 16574, 15091, 14977, 14171, 13687, 13155, 12558, 11600, 10827, 10436, 9851, 9794, 8787, 7993, 6901, 6422, 5506, 4839, 4144, 3433, 2936, 2615), + (346205, 340570, 342668, 328475, 319010, 312898, 308153, 296752, 289639, 290466, 296190, 303871, 309886, 317436, 315487, 316696, 325772, 331694, 345815, 354696, 354899, 351727, 354579, 341702, 336421, 321116, 292261, 261874, 242407, 229488, 208939, 184147, 162662, 147361, 140424, 134336, 126929, 125404, 122764, 116004, 105590, 100813, 95021, 90950, 85036, 79391, 72952, 66022, 59326, 52716, 46582, 42772, 38509, 34048, 30887, 28053, 26152, 23931, 22039, 20677, 19869, 19026, 18757, 18308, 14458, 13685, 12942, 12323, 11033, 10183, 10628, 10803, 10655, 10482, 10202, 10166, 9939, 10138, 10007, 10174, 9997, 9465, 9028, 8806, 8450, 7941, 7253, 6698, 6267, 5773), + (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 23, 91, 412, 1319, 2984, 5816, 10053, 16045, 24240, 35066, 47828, 62384, 78916, 97822, 112738, 124414, 130658, 140789, 153951, 168560, 179996, 194471, 212006, 225209, 228886, 239690, 245974, 253459, 255455, 260715, 259980, 256481, 252222, 249467, 240268, 238465, 238167, 231361, 223832, 220459, 222512, 220099, 219301, 221322, 229783, 239336, 258360, 271151, 218063, 213461, 207617, 196227, 174615, 160855, 165410, 163070, 157379, 149698, 140570, 131785, 119936, 113751, 106989, 99294, 89097, 78413, 68174, 60592, 52189, 43375, 35469, 29648, 24575, 20863), + (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 74, 392, 1351, 3906, 7847, 12857, 19913, 29108, 42475, 58287, 74163, 90724, 108375, 125886, 141559, 148061, 152871, 159725, 171298, 183536, 196136, 210831, 228757, 238731, 239616, 250036, 251759, 259593, 261832, 264864, 264702, 264070, 258117, 253678, 245440, 241342, 239843, 232493, 226118, 221644, 223440, 219833, 219659, 221271, 227123, 232865, 250646, 261796, 210136, 201824, 193109, 181831, 159280, 145235, 145929, 140266, 133082, 124350, 114441, 104655, 93223, 85899, 78800, 72081, 62645, 53214, 44086, 38481, 32219, 26867, 21443, 16899, 13680, 11508), + (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 7, 5, 17, 15, 31, 34, 38, 35, 45, 299, 295, 218, 247, 252, 254, 222, 307, 316, 385, 416, 463, 557, 670, 830, 889, 1025, 1149, 1356, 1488, 1835, 1929, 2130, 2362, 2494, 2884, 3160, 3487, 3916, 4196, 4619, 5032, 5709, 6347, 7288, 8139, 9344, 11002, 12809, 11504, 11918, 12927, 13642, 13298, 14015, 15751, 17445, 18591, 19682, 20969, 21629, 22549, 23619, 25288, 26293, 27038, 27039, 27070, 27750, 27244, 25905, 24357, 22561, 21794, 20595), + (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 6, 8, 0, 8, 21, 34, 49, 84, 97, 368, 401, 414, 557, 654, 631, 689, 698, 858, 1031, 1120, 1263, 1614, 1882, 2137, 2516, 2923, 3132, 3741, 4259, 4930, 5320, 5948, 6548, 7463, 8309, 9142, 10321, 11167, 12062, 13317, 15238, 16706, 18236, 20336, 23407, 27024, 32502, 37334, 34454, 38080, 41811, 44490, 45247, 46830, 53616, 58798, 63224, 66841, 71086, 73654, 77334, 82062, 87314, 92207, 94603, 94113, 92753, 93174, 91812, 87757, 84255, 79723, 77536, 74173), + (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 5, 0, 11, 35, 137, 331, 803, 1580, 2361, 3632, 4866, 6849, 8754, 10422, 12316, 14152, 16911, 19788, 22822, 27329, 31547, 35711, 38932, 42956, 46466, 49983, 52885, 55178, 56549, 57632, 57770, 57427, 56348, 55593, 55554, 53266, 51084, 49342, 48555, 47067, 45789, 44988, 44624, 44238, 46267, 46203, 36964, 33866, 31701, 28770, 25174, 22702, 21934, 20638, 19051, 17073, 15381, 13736, 11690, 10368, 9350, 8375, 7063, 6006, 5044, 4030, 3420, 2612, 2006, 1709, 1264, 1018), + (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 4, 6, 11, 20, 68, 179, 480, 1077, 2094, 3581, 5151, 7047, 9590, 12434, 15039, 17257, 19098, 21324, 24453, 27813, 32316, 37281, 43597, 49647, 53559, 58888, 62375, 67219, 70956, 73547, 74904, 75994, 76224, 74979, 72064, 70330, 68944, 66527, 63073, 60899, 60968, 58756, 57647, 56301, 57246, 57068, 59027, 59187, 47549, 44425, 40976, 38077, 32904, 29431, 29491, 28020, 26086, 24069, 21742, 19498, 17400, 15738, 14451, 13107, 11568, 10171, 8530, 7273, 6488, 5372, 4499, 3691, 3259, 2657)] + + types = ['Males single', 'Females single', + 'Males married', 'Females married', + 'Males widowed', 'Females widowed', + 'Males divorced', 'Females divorced'] + + pyramid_chart = pygal.Pyramid(human_readable=True, legend_at_bottom=True) + pyramid_chart.title = 'England population by age in 2010 (source: ons.gov.uk)' + pyramid_chart.x_labels = map(lambda x: str(x) if not x % 5 else '', range(90)) + for type, age in zip(types, ages): + pyramid_chart.add(type, age) + + +Worldmap charts +--------------- + +Basic +~~~~~ + +Highlight some countries: + +.. pygal-code:: + + worldmap_chart = pygal.Worldmap() + worldmap_chart.title = 'Some countries' + worldmap_chart.add('F countries', ['fr', 'fi']) + worldmap_chart.add('M countries', ['ma', 'mc', 'md', 'me', 'mg', + 'mk', 'ml', 'mm', 'mn', 'mo', + 'mr', 'mt', 'mu', 'mv', 'mw', + 'mx', 'my', 'mz']) + worldmap_chart.add('U countries', ['ua', 'ug', 'us', 'uy', 'uz']) + + +You can also specify an number for a country: + +.. pygal-code:: + + worldmap_chart = pygal.Worldmap() + worldmap_chart.title = 'Minimum deaths by capital punishement (source: Amnesty International)' + worldmap_chart.add('In 2012', { + 'af': 14, + 'bd': 1, + 'by': 3, + 'cn': 1000, + 'gm': 9, + 'in': 1, + 'ir': 314, + 'iq': 129, + 'jp': 7, + 'kp': 6, + 'pk': 1, + 'ps': 6, + 'sa': 79, + 'so': 6, + 'sd': 5, + 'tw': 6, + 'ae': 1, + 'us': 43, + 'ye': 28 + }) + + +The following countries are supported: + + - `ad`: Andorra + - `ae`: United Arab Emirates + - `af`: Afghanistan + - `al`: Albania + - `am`: Armenia + - `ao`: Angola + - `aq`: Antarctica + - `ar`: Argentina + - `at`: Austria + - `au`: Australia + - `az`: Azerbaijan + - `ba`: Bosnia and Herzegovina + - `bd`: Bangladesh + - `be`: Belgium + - `bf`: Burkina Faso + - `bg`: Bulgaria + - `bh`: Bahrain + - `bi`: Burundi + - `bj`: Benin + - `bn`: Brunei Darussalam + - `bo`: Bolivia, Plurinational State of + - `br`: Brazil + - `bt`: Bhutan + - `bw`: Botswana + - `by`: Belarus + - `bz`: Belize + - `ca`: Canada + - `cd`: Congo, the Democratic Republic of the + - `cf`: Central African Republic + - `cg`: Congo + - `ch`: Switzerland + - `ci`: Cote d'Ivoire + - `cl`: Chile + - `cm`: Cameroon + - `cn`: China + - `co`: Colombia + - `cr`: Costa Rica + - `cu`: Cuba + - `cv`: Cape Verde + - `cy`: Cyprus + - `cz`: Czech Republic + - `de`: Germany + - `dj`: Djibouti + - `dk`: Denmark + - `do`: Dominican Republic + - `dz`: Algeria + - `ec`: Ecuador + - `ee`: Estonia + - `eg`: Egypt + - `eh`: Western Sahara + - `er`: Eritrea + - `es`: Spain + - `et`: Ethiopia + - `fi`: Finland + - `fr`: France + - `ga`: Gabon + - `gb`: United Kingdom + - `ge`: Georgia + - `gf`: French Guiana + - `gh`: Ghana + - `gl`: Greenland + - `gm`: Gambia + - `gn`: Guinea + - `gq`: Equatorial Guinea + - `gr`: Greece + - `gt`: Guatemala + - `gu`: Guam + - `gw`: Guinea-Bissau + - `gy`: Guyana + - `hk`: Hong Kong + - `hn`: Honduras + - `hr`: Croatia + - `ht`: Haiti + - `hu`: Hungary + - `id`: Indonesia + - `ie`: Ireland + - `il`: Israel + - `in`: India + - `iq`: Iraq + - `ir`: Iran, Islamic Republic of + - `is`: Iceland + - `it`: Italy + - `jm`: Jamaica + - `jo`: Jordan + - `jp`: Japan + - `ke`: Kenya + - `kg`: Kyrgyzstan + - `kh`: Cambodia + - `kp`: Korea, Democratic People's Republic of + - `kr`: Korea, Republic of + - `kw`: Kuwait + - `kz`: Kazakhstan + - `la`: Lao People's Democratic Republic + - `lb`: Lebanon + - `li`: Liechtenstein + - `lk`: Sri Lanka + - `lr`: Liberia + - `ls`: Lesotho + - `lt`: Lithuania + - `lu`: Luxembourg + - `lv`: Latvia + - `ly`: Libyan Arab Jamahiriya + - `ma`: Morocco + - `mc`: Monaco + - `md`: Moldova, Republic of + - `me`: Montenegro + - `mg`: Madagascar + - `mk`: Macedonia, the former Yugoslav Republic of + - `ml`: Mali + - `mm`: Myanmar + - `mn`: Mongolia + - `mo`: Macao + - `mr`: Mauritania + - `mt`: Malta + - `mu`: Mauritius + - `mv`: Maldives + - `mw`: Malawi + - `mx`: Mexico + - `my`: Malaysia + - `mz`: Mozambique + - `na`: Namibia + - `ne`: Niger + - `ng`: Nigeria + - `ni`: Nicaragua + - `nl`: Netherlands + - `no`: Norway + - `np`: Nepal + - `nz`: New Zealand + - `om`: Oman + - `pa`: Panama + - `pe`: Peru + - `pg`: Papua New Guinea + - `ph`: Philippines + - `pk`: Pakistan + - `pl`: Poland + - `pr`: Puerto Rico + - `ps`: Palestine, State of + - `pt`: Portugal + - `py`: Paraguay + - `re`: Reunion + - `ro`: Romania + - `rs`: Serbia + - `ru`: Russian Federation + - `rw`: Rwanda + - `sa`: Saudi Arabia + - `sc`: Seychelles + - `sd`: Sudan + - `se`: Sweden + - `sg`: Singapore + - `sh`: Saint Helena, Ascension and Tristan da Cunha + - `si`: Slovenia + - `sk`: Slovakia + - `sl`: Sierra Leone + - `sm`: San Marino + - `sn`: Senegal + - `so`: Somalia + - `sr`: Suriname + - `st`: Sao Tome and Principe + - `sv`: El Salvador + - `sy`: Syrian Arab Republic + - `sz`: Swaziland + - `td`: Chad + - `tg`: Togo + - `th`: Thailand + - `tj`: Tajikistan + - `tl`: Timor-Leste + - `tm`: Turkmenistan + - `tn`: Tunisia + - `tr`: Turkey + - `tw`: Taiwan, Province of China + - `tz`: Tanzania, United Republic of + - `ua`: Ukraine + - `ug`: Uganda + - `us`: United States + - `uy`: Uruguay + - `uz`: Uzbekistan + - `va`: Holy See (Vatican City State) + - `ve`: Venezuela, Bolivarian Republic of + - `vn`: Viet Nam + - `ye`: Yemen + - `yt`: Mayotte + - `za`: South Africa + - `zm`: Zambia + - `zw`: Zimbabwe + + +Country charts +-------------- + +As of now, only France is available. As other country are implemented, this will be externalized in other packages. +(Please submit pull requests :)) + +French map +~~~~~~~~~~ + +Highlight some departments: + + +.. pygal-code:: + + fr_chart = pygal.FrenchMap_Departments() + fr_chart.title = 'Some departments' + fr_chart.add('Métropole', ['69', '92', '13']) + fr_chart.add('Corse', ['2A', '2B']) + fr_chart.add('DOM COM', ['971', '972', '973', '974']) + +You can also specify an number for a department: + +.. pygal-code:: + + fr_chart = pygal.FrenchMap_Departments(human_readable=True) + fr_chart.title = 'Population by department' + fr_chart.add('In 2011', { + '01': 603827, + '02': 541302, + '03': 342729, + '04': 160959, + '05': 138605, + '06': 1081244, + '07': 317277, + '08': 283110, + '09': 152286, + '10': 303997, + '11': 359967, + '12': 275813, + '13': 1975896, + '14': 685262, + '15': 147577, + '16': 352705, + '17': 625682, + '18': 311694, + '19': 242454, + '2A': 145846, + '2B': 168640, + '21': 525931, + '22': 594375, + '23': 122560, + '24': 415168, + '25': 529103, + '26': 487993, + '27': 588111, + '28': 430416, + '29': 899870, + '30': 718357, + '31': 1260226, + '32': 188893, + '33': 1463662, + '34': 1062036, + '35': 996439, + '36': 230175, + '37': 593683, + '38': 1215212, + '39': 261294, + '40': 387929, + '41': 331280, + '42': 749053, + '43': 224907, + '44': 1296364, + '45': 659587, + '46': 174754, + '47': 330866, + '48': 77156, + '49': 790343, + '50': 499531, + '51': 566571, + '52': 182375, + '53': 307031, + '54': 733124, + '55': 193557, + '56': 727083, + '57': 1045146, + '58': 218341, + '59': 2579208, + '60': 805642, + '61': 290891, + '62': 1462807, + '63': 635469, + '64': 656608, + '65': 229228, + '66': 452530, + '67': 1099269, + '68': 753056, + '69': 1744236, + '70': 239695, + '71': 555999, + '72': 565718, + '73': 418949, + '74': 746994, + '75': 2249975, + '76': 1251282, + '77': 1338427, + '78': 1413635, + '79': 370939, + '80': 571211, + '81': 377675, + '82': 244545, + '83': 1012735, + '84': 546630, + '85': 641657, + '86': 428447, + '87': 376058, + '88': 378830, + '89': 342463, + '90': 143348, + '91': 1225191, + '92': 1581628, + '93': 1529928, + '94': 1333702, + '95': 1180365, + '971': 404635, + '972': 392291, + '973': 237549, + '974': 828581, + '976': 212645 + }) + +You can do the same with regions: + + +.. pygal-code:: + + fr_chart = pygal.FrenchMap_Regions() + fr_chart.title = 'Some regions' + fr_chart.add('Métropole', ['82', '11', '93']) + fr_chart.add('Corse', ['94']) + fr_chart.add('DOM COM', ['01', '02', '03', '04']) + + +You can also specify a number for a region and use a department to region aggregation: + + +.. pygal-code:: + + from pygal.graph.frenchmap import aggregate_regions + fr_chart = pygal.FrenchMap_Regions(human_readable=True) + fr_chart.title = 'Population by region' + fr_chart.add('In 2011', aggregate_regions({ + '01': 603827, + '02': 541302, + '03': 342729, + '04': 160959, + '05': 138605, + '06': 1081244, + '07': 317277, + '08': 283110, + '09': 152286, + '10': 303997, + '11': 359967, + '12': 275813, + '13': 1975896, + '14': 685262, + '15': 147577, + '16': 352705, + '17': 625682, + '18': 311694, + '19': 242454, + '2A': 145846, + '2B': 168640, + '21': 525931, + '22': 594375, + '23': 122560, + '24': 415168, + '25': 529103, + '26': 487993, + '27': 588111, + '28': 430416, + '29': 899870, + '30': 718357, + '31': 1260226, + '32': 188893, + '33': 1463662, + '34': 1062036, + '35': 996439, + '36': 230175, + '37': 593683, + '38': 1215212, + '39': 261294, + '40': 387929, + '41': 331280, + '42': 749053, + '43': 224907, + '44': 1296364, + '45': 659587, + '46': 174754, + '47': 330866, + '48': 77156, + '49': 790343, + '50': 499531, + '51': 566571, + '52': 182375, + '53': 307031, + '54': 733124, + '55': 193557, + '56': 727083, + '57': 1045146, + '58': 218341, + '59': 2579208, + '60': 805642, + '61': 290891, + '62': 1462807, + '63': 635469, + '64': 656608, + '65': 229228, + '66': 452530, + '67': 1099269, + '68': 753056, + '69': 1744236, + '70': 239695, + '71': 555999, + '72': 565718, + '73': 418949, + '74': 746994, + '75': 2249975, + '76': 1251282, + '77': 1338427, + '78': 1413635, + '79': 370939, + '80': 571211, + '81': 377675, + '82': 244545, + '83': 1012735, + '84': 546630, + '85': 641657, + '86': 428447, + '87': 376058, + '88': 378830, + '89': 342463, + '90': 143348, + '91': 1225191, + '92': 1581628, + '93': 1529928, + '94': 1333702, + '95': 1180365, + '971': 404635, + '972': 392291, + '973': 237549, + '974': 828581, + '976': 212645 + })) + +Next: `Styles `_ diff --git a/docs/conf.py b/docs/conf.py index e829543..a787704 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,6 +36,7 @@ extensions = [ 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', + 'pygal_sphinx_directives' ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/custom_styles.rst b/docs/custom_styles.rst new file mode 100644 index 0000000..3c7a31a --- /dev/null +++ b/docs/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 `_) + +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 `_ + diff --git a/docs/documentation.rst b/docs/documentation.rst new file mode 100644 index 0000000..b63a3d8 --- /dev/null +++ b/docs/documentation.rst @@ -0,0 +1,17 @@ +=============== + Documentation +=============== + + +User documentation +================== + +- `First steps `_ - learn how to very simply make beautiful charts. +- `Charts types `_ - see what pygal can do for you. +- `Styles `_ - change the style. +- `Basic customizations `_ - start to improve your charts. +- `Interpolations `_ - smooth your lines. +- `Sparklines `_ - create simple sparklines. +- `Metadata `_ - enrich your graph. +- `Other customizations `_ - customize all the things. +- `Embedding in a web page `_ - see several ways to use pygal on the intertubes. diff --git a/docs/download.rst b/docs/download.rst new file mode 100644 index 0000000..eb9c38d --- /dev/null +++ b/docs/download.rst @@ -0,0 +1,31 @@ +========== + Download +========== + +PyPI +==== + +pygal is `available on PyPI `_. To +install, just type as superuser:: + + pip install pygal + +Git Repository +============== + +If you want the development version of pygal, take a look at the +:codelink:`git repository on GitHub`, or clone it with:: + + git clone git://github.com/Kozea/pygal.git + +You can also download `the development snapshot from github `_. + +Linux Distribution Packages +=========================== + +Pygal has been packaged for: + +- `Fedora `_ by ralph +- `Gentoo `_ by Ben de Groot + +If you are interested in creating packages for Linux distributions, `contact us `_. diff --git a/docs/first_steps.rst b/docs/first_steps.rst new file mode 100644 index 0000000..a1492e0 --- /dev/null +++ b/docs/first_steps.rst @@ -0,0 +1,68 @@ +=============== + Documentation +=============== + + +First steps +=========== + +First you need to download the pygal package, see the `download page `_. + +When it's done, you are ready to make your first chart: + +.. code-block:: python + + import pygal # First import pygal + bar_chart = pygal.Bar() # Then create a bar graph object + bar_chart.add('Fibonacci', [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]) # Add some values + bar_chart.render_to_file('bar_chart.svg') # Save the svg to a file + +Now you have a svg file called `bar_chart.svg` in your current directory. + +You can open it with various programs such as your web browser, inkscape or any svg compatible viewer. + +The resulting chart will be tho following: + +.. pygal-code:: + + bar_chart = pygal.Bar() + bar_chart.add('Fibonacci', [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]) + +To make a multiple series graph just add another one: + +.. pygal-code:: + + bar_chart = pygal.Bar() + 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]) + +If you want to stack them, use `StackedBar` instead of `Bar`: + +.. pygal-code:: + + bar_chart = pygal.StackedBar() + 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]) + + +You can also make it horizontal with `HorizontalStackedBar`: + +.. pygal-code:: + + bar_chart = pygal.HorizontalStackedBar() + 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]) + + +And finally add a title and some labels: + +.. pygal-code:: + + bar_chart = pygal.HorizontalStackedBar() + bar_chart.title = "Remarquable sequences" + bar_chart.x_labels = map(str, range(11)) + 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 `_ diff --git a/docs/index.rst b/docs/index.rst index 9dbf0c0..8eb7dba 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,108 @@ -.. pygal documentation master file, created by - sphinx-quickstart on Wed Jul 1 14:31:10 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +===== +Pygal +===== -Welcome to pygal's documentation! -================================= +Presentation +============ + +pygal is a SVG charting library written in python. + +.. pygal:: 300 200 + + chart = pygal.HorizontalBar(y_label_rotation=-25) + chart.x_labels = 'one', 'two', 'three', 'four', 'five' + chart.add('red', [1, 2, 3, 1, 2]) + chart.add('green', [4, 3, 0, 1, 2]) + +.. pygal:: 300 200 + + chart = pygal.Line(x_label_rotation=25, fill=True, style=pygal.style.NeonStyle, interpolate='cubic') + chart.x_labels = 'one', 'two', 'three', 'four', 'five' + chart.add('red', [1, 2, 3, 1, 2]) + chart.add('green', [4, 3, 0, 1, 2]) + +.. pygal:: 300 200 + + chart = pygal.Pie() + chart.x_labels = 'one', 'two', 'three', 'four', 'five' + chart.add('red', [1, 2, 3, 1, 2]) + chart.add('green', [4, 3, 0, 1, 2]) + +.. pygal:: 300 200 + + chart = pygal.Radar(fill=True, style=pygal.style.NeonStyle) + chart.x_labels = 'one', 'two', 'three', 'four', 'five' + chart.add('red', [1, 2, 3, 1, 2]) + chart.add('green', [4, 3, 0, 1, 2]) + +It features various graph types: + +- `Bar charts `_ + +- `Line charts `_ + +- `XY charts `_ + +- `Pie charts `_ + +- `Radar charts `_ + +- `Box plot `_ + +- `Dot charts `_ + +- `Pyramid charts `_ + +- `Funnel charts `_ + +- `Gauge charts `_ + +- `Worldmap charts `_ + +- `Country charts `_ + + +Python/Css styling with some pre-defined themes. See `styling `_. + +And a lot of options to `customize the charts. `_ + + +Get it ! +======== + +- Get the package on `pypi `_ +- Fork me on `github `_ + +More information in the `download page `_ + + +Get started +=========== + +Start `here `_ to make your first steps. + + +Technical Description +===================== + +As of now pygal is known to work for python 2.6, 2.7 and 3.2, 3.3, 3.4. + + +Needed dependencies +------------------- + +pygal uses `lxml `_ to generate the svg, this is the only needed dependency. + + +Optional dependencies +--------------------- + +PNG output requires `CairoSVG `_, `tinycss `_ and `cssselect `_. +Install those with ``pip install CairoSVG tinycss cssselect``. + +Unit testing needs `py.test `_ or `nosetests `_. + +Visual testing is based on `flask `_. Contents: @@ -19,4 +117,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/docs/interpolations.rst b/docs/interpolations.rst new file mode 100644 index 0000000..7f680f8 --- /dev/null +++ b/docs/interpolations.rst @@ -0,0 +1,120 @@ +=============== + Documentation +=============== + + +Interpolations +============== + + +.. contents:: + + +Without interpolation: +---------------------- + +``interpolate`` + +.. pygal-code:: + + chart = pygal.Line() + chart.add('line', [1, 5, 17, 12, 5, 10]) + +With cubic interpolation: +------------------------- + +``interpolate`` + +.. pygal-code:: + + chart = pygal.Line(interpolate='cubic') + chart.add('line', [1, 5, 17, 12, 5, 10]) + + +With quadratic interpolation: +----------------------------- + +``interpolate`` + +.. pygal-code:: + + chart = pygal.Line(interpolate='quadratic') + chart.add('line', [1, 5, 17, 12, 5, 10]) + + +With lagrange interpolation: +---------------------------- + +``interpolate`` + +.. pygal-code:: + + chart = pygal.Line(interpolate='lagrange') + chart.add('line', [1, 5, 17, 12, 5, 10]) + + +With trigonometric interpolation: +--------------------------------- + +``interpolate`` + +.. pygal-code:: + + chart = pygal.Line(interpolate='trigonometric') + chart.add('line', [1, 5, 17, 12, 5, 10]) + + +With hermite interpolation: +--------------------------- + +``interpolate`` + +.. pygal-code:: + + chart = pygal.Line(interpolate='hermite') + chart.add('line', [1, 5, 17, 12, 5, 10]) + + +For hermite you can also pass additionnal parameters to configure tangent behaviour: + + +.. pygal-code:: + + chart = pygal.Line(interpolate='hermite', interpolation_parameters={'type': 'finite_difference'}) + chart.add('line', [1, 5, 17, 12, 5, 10]) + + +.. pygal-code:: + + chart = pygal.Line(interpolate='hermite', interpolation_parameters={'type': 'cardinal', 'c': .75}) + chart.add('line', [1, 5, 17, 12, 5, 10]) + + +.. pygal-code:: + + chart = pygal.Line(interpolate='hermite', interpolation_parameters={'type': 'kochanek_bartels', 'b': -1, 'c': 1, 't': 1}) + chart.add('line', [1, 5, 17, 12, 5, 10]) + +For more information see the `wikipedia article `_ + + +Interpolation precision +----------------------- + +``interpolation_precision`` + +You can change the resolution of the interpolation with the help of `interpolation_precision`: + + +.. pygal-code:: + + chart = pygal.Line(interpolate='quadratic') + chart.add('line', [1, 5, 17, 12, 5, 10]) + +.. pygal-code:: + + chart = pygal.Line(interpolate='quadratic', interpolation_precision=3) + chart.add('line', [1, 5, 17, 12, 5, 10]) + + +Next: `Sparklines `_ diff --git a/docs/metadata.rst b/docs/metadata.rst new file mode 100644 index 0000000..9d01896 --- /dev/null +++ b/docs/metadata.rst @@ -0,0 +1,99 @@ +=============== + Documentation +=============== + + +Metadata +======== + +.. contents:: + + +Labels +------ + +You can add per value metadata like labels, by specifying a dictionary instead of a value: + +.. pygal-code:: + + chart = pygal.Bar() + chart.add('Red', [{'value': 2, 'label': 'This is red'}]) + chart.add('Green', [{'value': 4, 'label': 'This is green'}]) + chart.add('Yellow', 7) + chart.add('Blue', [{'value': 5}]) + chart.add('Violet', [{'value': 3, 'label': 'This is violet'}]) + + +Links +----- + +Basic +~~~~~ + +You can also add hyper links: + +.. pygal-code:: + + chart = pygal.Bar() + chart.add('Red', [{ + 'value': 2, + 'label': 'This is red', + 'xlink': 'http://en.wikipedia.org/wiki/Red'}]) + + chart.add('Green', [{ + 'value': 4, + 'label': 'This is green', + 'xlink': 'http://en.wikipedia.org/wiki/Green'}]) + + chart.add('Yellow', 7) + + chart.add('Blue', [{ + 'value': 5, + 'xlink': 'http://en.wikipedia.org/wiki/Blue'}]) + + chart.add('Violet', [{ + 'value': 3, + 'label': 'This is violet', + 'xlink': 'http://en.wikipedia.org/wiki/Violet_(color)'}]) + + +Advanced +~~~~~~~~ + +You can specify a dictionary to xlink with all links attributes: + +.. pygal-code:: + + chart = pygal.Bar() + chart.add('Red', [{ + 'value': 2, + 'label': 'This is red', + 'xlink': {'href': 'http://en.wikipedia.org/wiki/Red'}}]) + + chart.add('Green', [{ + 'value': 4, + 'label': 'This is green', + 'xlink': { + 'href': 'http://en.wikipedia.org/wiki/Green', + 'target': '_top'} + }]) + + chart.add('Yellow', 7) + + chart.add('Blue', [{ + 'value': 5, + 'xlink': { + 'href': 'http://en.wikipedia.org/wiki/Blue', + 'target': '_blank'} + }]) + + chart.add('Violet', [{ + 'value': 3, + 'label': 'This is violet', + 'xlink': { + 'href': 'http://en.wikipedia.org/wiki/Violet_(color)', + 'target': '_self'} + }]) + + +Next: `Other customizations `_ diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000..4da0b42 --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,7 @@ +pygal +===== + +.. toctree:: + :maxdepth: 4 + + pygal diff --git a/docs/other_customizations.rst b/docs/other_customizations.rst new file mode 100644 index 0000000..9eac182 --- /dev/null +++ b/docs/other_customizations.rst @@ -0,0 +1,122 @@ +=============== + Documentation +=============== + + +Other customizations +==================== + +.. contents:: + + +Logarithmic +----------- + +``logarithmic`` + +You can set the scale to be logarithmic: + +.. pygal-code:: + + chart = pygal.Line(logarithmic=True) + values = [1, 3, 43, 123, 1231, 23192] + chart.x_labels = map(str, values) + chart.add('log example', values) + +.. caution:: + + Negative values are ignored + + +Custom css and js +----------------- + +``css, js`` + +You can add or replace css/js files in pygal using the `css` and `js` array options. +These lists contain absolute filenames and/or external URI. (Relative filenames are relative to pygal internal files) + +Default: + +.. code-block:: + + css = ['style.css', 'graph.css'] + js = [ + 'http://kozea.github.com/pygal.js/javascripts/svg.jquery.js', + 'http://kozea.github.com/pygal.js/javascripts/pygal-tooltips.js' + ] + + +Legend box size +--------------- + +``legend_box_size`` + +You can change the size of the rectangle next to the legend: + +.. pygal-code:: + + chart = pygal.Line(legend_box_size=50) + values = [1, 3, 43, 123, 1231, 23192] + chart.x_labels = map(str, values) + chart.add('log example', values) + + +Rounded bars +------------ + +``rounded_bars`` + +You can add a round effect to bar diagrams with `rounded_bars`: + +.. pygal-code:: + + chart = pygal.Bar(rounded_bars=20) + chart.add('values', [3, 10, 7, 2, 9, 7]) + + +Pretty print +------------ + +``pretty_print`` + +You can enable pretty print if you want to edit the source at hand (look at this frame source): + +.. pygal-code:: + + chart = pygal.Bar(pretty_print=True) + chart.add('values', [3, 10, 7, 2, 9, 7]) + + +Static options +-------------- + +``print_values, print_zeroes`` + +By default, when the graph is viewed using a non javascript compatible +viewer or as an image, all the values are displayed on the graph. + +It can be disabled by setting `print_values` to `False`. + +`print_zeroes` can be enabled to display static values even if equal to zero. + + +Disable xml declaration +----------------------- + +``disable_xml_declaration`` + +When you want to embed directly your SVG in your html, +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. + diff --git a/docs/parametric_styles.rst b/docs/parametric_styles.rst new file mode 100644 index 0000000..c0995e8 --- /dev/null +++ b/docs/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]) diff --git a/docs/pygal.graph.rst b/docs/pygal.graph.rst new file mode 100644 index 0000000..0b5a627 --- /dev/null +++ b/docs/pygal.graph.rst @@ -0,0 +1,190 @@ +pygal.graph package +=================== + +Submodules +---------- + +pygal.graph.bar module +---------------------- + +.. automodule:: pygal.graph.bar + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.base module +----------------------- + +.. automodule:: pygal.graph.base + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.box module +---------------------- + +.. automodule:: pygal.graph.box + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.dot module +---------------------- + +.. automodule:: pygal.graph.dot + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.funnel module +------------------------- + +.. automodule:: pygal.graph.funnel + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.gauge module +------------------------ + +.. automodule:: pygal.graph.gauge + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.graph module +------------------------ + +.. automodule:: pygal.graph.graph + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.histogram module +---------------------------- + +.. automodule:: pygal.graph.histogram + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.horizontal module +----------------------------- + +.. automodule:: pygal.graph.horizontal + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.horizontalbar module +-------------------------------- + +.. automodule:: pygal.graph.horizontalbar + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.horizontalstackedbar module +--------------------------------------- + +.. automodule:: pygal.graph.horizontalstackedbar + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.line module +----------------------- + +.. automodule:: pygal.graph.line + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.map module +---------------------- + +.. automodule:: pygal.graph.map + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.pie module +---------------------- + +.. automodule:: pygal.graph.pie + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.pyramid module +-------------------------- + +.. automodule:: pygal.graph.pyramid + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.radar module +------------------------ + +.. automodule:: pygal.graph.radar + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.stackedbar module +----------------------------- + +.. automodule:: pygal.graph.stackedbar + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.stackedline module +------------------------------ + +.. automodule:: pygal.graph.stackedline + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.time module +----------------------- + +.. automodule:: pygal.graph.time + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.treemap module +-------------------------- + +.. automodule:: pygal.graph.treemap + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.verticalpyramid module +---------------------------------- + +.. automodule:: pygal.graph.verticalpyramid + :members: + :undoc-members: + :show-inheritance: + +pygal.graph.xy module +--------------------- + +.. automodule:: pygal.graph.xy + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: pygal.graph + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/pygal.rst b/docs/pygal.rst new file mode 100644 index 0000000..7739f37 --- /dev/null +++ b/docs/pygal.rst @@ -0,0 +1,119 @@ +pygal package +============= + +Subpackages +----------- + +.. toctree:: + + pygal.graph + pygal.maps + pygal.test + +Submodules +---------- + +pygal.adapters module +--------------------- + +.. automodule:: pygal.adapters + :members: + :undoc-members: + :show-inheritance: + +pygal.colors module +------------------- + +.. automodule:: pygal.colors + :members: + :undoc-members: + :show-inheritance: + +pygal.config module +------------------- + +.. automodule:: pygal.config + :members: + :undoc-members: + :show-inheritance: + +pygal.etree module +------------------ + +.. automodule:: pygal.etree + :members: + :undoc-members: + :show-inheritance: + +pygal.interpolate module +------------------------ + +.. automodule:: pygal.interpolate + :members: + :undoc-members: + :show-inheritance: + +pygal.serie module +------------------ + +.. automodule:: pygal.serie + :members: + :undoc-members: + :show-inheritance: + +pygal.state module +------------------ + +.. automodule:: pygal.state + :members: + :undoc-members: + :show-inheritance: + +pygal.style module +------------------ + +.. automodule:: pygal.style + :members: + :undoc-members: + :show-inheritance: + +pygal.svg module +---------------- + +.. automodule:: pygal.svg + :members: + :undoc-members: + :show-inheritance: + +pygal.table module +------------------ + +.. automodule:: pygal.table + :members: + :undoc-members: + :show-inheritance: + +pygal.util module +----------------- + +.. automodule:: pygal.util + :members: + :undoc-members: + :show-inheritance: + +pygal.view module +----------------- + +.. automodule:: pygal.view + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: pygal + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/pygal.test.rst b/docs/pygal.test.rst new file mode 100644 index 0000000..4e08263 --- /dev/null +++ b/docs/pygal.test.rst @@ -0,0 +1,190 @@ +pygal.test package +================== + +Submodules +---------- + +pygal.test.conftest module +-------------------------- + +.. automodule:: pygal.test.conftest + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_bar module +-------------------------- + +.. automodule:: pygal.test.test_bar + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_box module +-------------------------- + +.. automodule:: pygal.test.test_box + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_colors module +----------------------------- + +.. automodule:: pygal.test.test_colors + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_config module +----------------------------- + +.. automodule:: pygal.test.test_config + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_date module +--------------------------- + +.. automodule:: pygal.test.test_date + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_donut module +---------------------------- + +.. automodule:: pygal.test.test_donut + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_graph module +---------------------------- + +.. automodule:: pygal.test.test_graph + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_histogram module +-------------------------------- + +.. automodule:: pygal.test.test_histogram + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_interpolate module +---------------------------------- + +.. automodule:: pygal.test.test_interpolate + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_line module +--------------------------- + +.. automodule:: pygal.test.test_line + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_maps module +--------------------------- + +.. automodule:: pygal.test.test_maps + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_pie module +-------------------------- + +.. automodule:: pygal.test.test_pie + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_serie_config module +----------------------------------- + +.. automodule:: pygal.test.test_serie_config + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_sparktext module +-------------------------------- + +.. automodule:: pygal.test.test_sparktext + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_stacked module +------------------------------ + +.. automodule:: pygal.test.test_stacked + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_style module +---------------------------- + +.. automodule:: pygal.test.test_style + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_table module +---------------------------- + +.. automodule:: pygal.test.test_table + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_util module +--------------------------- + +.. automodule:: pygal.test.test_util + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_view module +--------------------------- + +.. automodule:: pygal.test.test_view + :members: + :undoc-members: + :show-inheritance: + +pygal.test.test_xml_filters module +---------------------------------- + +.. automodule:: pygal.test.test_xml_filters + :members: + :undoc-members: + :show-inheritance: + +pygal.test.utils module +----------------------- + +.. automodule:: pygal.test.utils + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: pygal.test + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sparks.rst b/docs/sparks.rst new file mode 100644 index 0000000..e16ac4d --- /dev/null +++ b/docs/sparks.rst @@ -0,0 +1,80 @@ +=============== + Documentation +=============== + + +Sparklines +========== + +pygal provides a simple way to get beautiful sparklines. + + +.. contents:: + + +Basic +----- + +.. pygal-code:: sparkline + + 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 `_ diff --git a/docs/styles.rst b/docs/styles.rst new file mode 100644 index 0000000..0615325 --- /dev/null +++ b/docs/styles.rst @@ -0,0 +1,9 @@ +=============== + Documentation +=============== + +There are three ways to style the charts: + +- Using `built-in themes `_ +- Using `parametric themes `_ +- Using `custom themes `_ diff --git a/docs/support.rst b/docs/support.rst new file mode 100644 index 0000000..992dee6 --- /dev/null +++ b/docs/support.rst @@ -0,0 +1,11 @@ +========= + Support +========= + + +Github +====== + +Submit your bug reports and your feature requests to the `github bug tracker `_. +Never hesitate to fork the project on github. +Pull requests are always welcomed. diff --git a/docs/web.rst b/docs/web.rst new file mode 100644 index 0000000..acc43b4 --- /dev/null +++ b/docs/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 + + + + + + + +
+ +
+ + + +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 + + + + + + + + + +
+ + + + + + + + + Pygal + + + + + +
+ + + +You can use `explicit_size` to set the svg size from the `width`, `height` properties. + diff --git a/pygal/style.py b/pygal/style.py index 68b007b..33ca6e3 100644 --- a/pygal/style.py +++ b/pygal/style.py @@ -301,6 +301,18 @@ SolidColorStyle = Style( '#0099C6', '#DD4477', '#74B217', '#B82E2E', '#316395', '#994499')) +RTDStyle = Style( + background='#fcfcfc', + plot_background='#ffffff', + foreground='#404040', + foreground_light='#202020', + foreground_dark='#606060', + opacity='.8', + opacity_hover='.9', + transition='400ms ease-in', + colors=[colors.rotate('#2980b9', i * 30) for i in range(16)]) + + styles = {'default': DefaultStyle, 'light': LightStyle, 'neon': NeonStyle,