From b9d0612314b1138588100ac9db657f1db3ed12df Mon Sep 17 00:00:00 2001 From: Florian Mounier Date: Wed, 21 Mar 2012 17:07:13 +0100 Subject: [PATCH] Add customizations --- pages/basic_customizations.rst | 268 +++++++++++++++++++++++++++++++++ pages/documentation.rst | 11 +- pages/interpolations.rst | 76 ++++++++++ pages/other_customizations.rst | 106 +++++++++++++ 4 files changed, 457 insertions(+), 4 deletions(-) create mode 100644 pages/basic_customizations.rst create mode 100644 pages/interpolations.rst create mode 100644 pages/other_customizations.rst diff --git a/pages/basic_customizations.rst b/pages/basic_customizations.rst new file mode 100644 index 0000000..b4bd49e --- /dev/null +++ b/pages/basic_customizations.rst @@ -0,0 +1,268 @@ +=============== + 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 argument as keyword args: + +.. code-block:: + + chart = pygal.XY(show_legend=False, human_readable=True, fill=True, x_scale=.25, y_scale=.25) + ... + + +Size +---- + +`width, height, explicit_size` + + +The simplest and usefull customizations is the svg size to render. +It indicates the desired size of the svg. + + +.. pygal-code:: 200 100 + + chart = pygal.Bar(width=200, height=100) + chart.add('1', 1) + chart.add('2', 2) + +You can also set `explicit_size` to True to add size attributes to the svg tag. + +Scaling +------- + +`x_scale, y_scale, include_x_axis` + + +Indicate a hint for the scale computation: + +.. pygal-code:: + + chart = pygal.Line() + chart.add('line', [.0002, .0005, .00035]) + +.. pygal-code:: + + chart = pygal.Line(y_scale=.0001) + chart.add('line', [.0002, .0005, .00035]) + + +You may want to always have the absissa in your graph: + +.. pygal-code:: + + chart = pygal.Line(y_scale=.0001, include_x_axis=True) + chart.add('line', [.0002, .0005, .00035]) + + +Title +----- + +`title` + +You can add a title to the chart by setting the title option: + +.. pygal-code:: + + chart = pygal.Line(title=u'Some points') + chart.add('line', [.0002, .0005, .00035]) + + +Labels +------ + +`x_labels, y_labels` + +You can specify x labels and y labels, depending on the graph type: + +.. pygal-code:: + + chart = pygal.Line() + chart.x_labels = 'Red', 'Blue', 'Green' + chart.y_labels = .0001, .0003, .0004, .00045, .0005 + chart.add('line', [.0002, .0005, .00035]) + + +Display +------- + +`show_legend, show dots` + +You can remove legend and dots by setting these at False + +.. pygal-code:: + + chart = pygal.Line(show_legend=False) + chart.add('line', [.0002, .0005, .00035]) + + +.. pygal-code:: + + chart = pygal.Line(show_dots=False) + chart.add('line', [.0002, .0005, .00035]) + +Rendering +--------- + +`fill, stroke, zero` + +You can disable line stroking: + +.. pygal-code:: + + chart = pygal.Line(stroke=False) + chart.add('line', [.0002, .0005, .00035]) + +And enable line filling: + +.. pygal-code:: + + chart = pygal.Line(fill=True) + chart.add('line', [.0002, .0005, .00035]) + +To fill to an other reference than zero: + +.. pygal-code:: + + chart = pygal.Line(fill=True, zero=.0004) + chart.add('line', [.0002, .0005, .00035]) + + +Font sizes +---------- + +`label_font_size, value_font_size, tooltip_font_size, title_font_size, legend_font_size` + + +Set the various font size + +.. pygal-code:: + + chart = pygal.Line(label_font_size=34, legend_font_size=8) + chart.add('line', [0, .0002, .0005, .00035]) + + +Label rotation +-------------- + +`x_label_rotation, y_label_rotation` + + +Allow label rotation (in degrees) to avoid axis cluttering: + +.. pygal-code:: + + chart = pygal.Line() + chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !'] + chart.add('line', [0, .0002, .0005, .00035]) + + +.. pygal-code:: + + chart = pygal.Line(x_label_rotation=20) + chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !'] + chart.add('line', [0, .0002, .0005, .00035]) + + +Human readable +-------------- + +`human_readable` + + +Display values in human readable form: + +1 230 000 -> 1.23M +.00 098 7 -> 987ยต + +.. pygal-code:: + + chart = pygal.Line(human_readable=True, y_scale=.0001) + chart.add('line', [0, .0002, .0005, .00035]) + + +No data text +------------ + +`no_data_text` + + +Text to display instead of the graph when no data is supplied: + +.. pygal-code:: + + chart = pygal.Line() + chart.add('line', []) + +.. pygal-code:: + + chart = pygal.Line(no_data_text='No result found') + chart.add('line', []) diff --git a/pages/documentation.rst b/pages/documentation.rst index 4d5270b..c413a32 100644 --- a/pages/documentation.rst +++ b/pages/documentation.rst @@ -6,12 +6,15 @@ User documentation ================== -- `First steps `_ -- `Charts types `_ -- `Styles `_ +- `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 chats. +- `Interpolations `_ - smooth your lines. +- `Other customizations `_ - customize all the things. Developper documentation ======================== -*TODO* +- `Create a chart type `_ - extend pygal. diff --git a/pages/interpolations.rst b/pages/interpolations.rst new file mode 100644 index 0000000..7080c6c --- /dev/null +++ b/pages/interpolations.rst @@ -0,0 +1,76 @@ +=============== + Documentation +=============== + + +Interpolations +============== + + +.. contents:: + +Interpolations need the `scipy python module `_. +To enable it just specify the interpolation type to: + +- linear +- nearest +- zero +- slinear +- quadratic +- cubic +- krogh +- barycentric +- univariate +- or an integer representing the order of the spline interpolator + +For more info see `interp1d definition on scipy `_ + + +Without interpolation: +---------------------- + +`interpolation` + +.. pygal-code:: + + chart = pygal.Line() + chart.add('line', [1, 5, 17, 12, 5, 10]) + +With cubic interpolation: +------------------------- + +`interpolation` + +.. pygal-code:: + + chart = pygal.Line(interpolate='cubic') + chart.add('line', [1, 5, 17, 12, 5, 10]) + +With krogh interpolation: +------------------------- + +`interpolation` + +.. pygal-code:: + + chart = pygal.Line(interpolate='krogh') + chart.add('line', [1, 5, 17, 12, 5, 10]) + + +Interpolation precision +----------------------- + +`interpolation_precision` + +You can change the resolution of the interpolation with the help of `interpolation_precision`: + + +.. pygal-code:: + + chart = pygal.Line(interpolate='krogh', interpolation_precision=15) + chart.add('line', [1, 5, 17, 12, 5, 10]) + +.. pygal-code:: + + chart = pygal.Line(interpolate='krogh', interpolation_precision=50) + chart.add('line', [1, 5, 17, 12, 5, 10]) diff --git a/pages/other_customizations.rst b/pages/other_customizations.rst new file mode 100644 index 0000000..2e3feb4 --- /dev/null +++ b/pages/other_customizations.rst @@ -0,0 +1,106 @@ +=============== + 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) + + +Custom css and js +----------------- + +`base_css, base_js` + +You can specify a css/js file to replace the one by default using `base_css` and `base_js` options. +These options take a filename in parameter. + + +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('rounded', [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. + + +Tooltip animation +----------------- + +`animation_steps` + +*Experimental* (might be slow sometimes) + +If you want some smoothing in tooltip display you can set animation_steps to a number. +The greater the number the slowest but detailed the animation: + + +.. pygal-code:: + + chart = pygal.Line(animation_steps=20) + values = [1, 3, 43, 123, 1231, 23192] + chart.x_labels = map(str, values) + chart.add('log example', values) + + +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. + +