Add customizations

13 years ago · b9d0612314
4 changed files with 457 additions and 4 deletions
--- a/pages/basic_customizations.rst
+++ 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 <https://github.com/Kozea/pygal/blob/master/pygal/config.py>`_). It can be changed in several ways:
+
+.. pygal::
+
+  from pygal import Config
+  config = Config()
+  config.show_legend = False
+  config.human_readable = True
+  config.fill = True
+  config.x_scale = config.y_scale = 0.25
+  chart = pygal.XY(config)
+  from math import cos, sin, pi
+  a = 2 * pi / 5.
+  chart.add('*', [(cos(i*a+pi/2.), sin(i*a+pi/2.)) for i in (0,2,4,1,3,0)])
+
+
+By instanciating it
+^^^^^^^^^^^^^^^^^^^
+
+Just import the config class and instanciate it:
+
+.. code-block::
+
+  from pygal import Config
+
+  config = Config()
+  config.show_legend = False
+  config.human_readable = True
+  config.fill = True
+  config.x_scale = .25
+  config.y_scale = .25
+  chart = pygal.XY(config)
+  ...
+
+By inheriting it
+^^^^^^^^^^^^^^^^
+
+Import the config class and override it:
+
+.. code-block::
+
+  from pygal import Config
+
+  class StarConfig(Config):
+      show_legend = False
+      human_readable = True
+      fill = True
+      x_scale = .25
+      y_scale = .25
+
+  chart = pygal.XY(StarConfig())
+  ...
+
+
+Using keyword args
+^^^^^^^^^^^^^^^^^^
+
+As a shorthand for a one shot config you can specify all config argument as keyword args:
+
+.. code-block::
+
+  chart = pygal.XY(show_legend=False, human_readable=True, fill=True, x_scale=.25, y_scale=.25)
+  ...
+
+
+Size
+----
+
+`width, height, explicit_size`
+
+
+The simplest and usefull customizations is the svg size to render.
+It indicates the desired size of the svg.
+
+
+.. pygal-code:: 200 100
+
+  chart = pygal.Bar(width=200, height=100)
+  chart.add('1', 1)
+  chart.add('2', 2)
+
+You can also set `explicit_size` to True to add size attributes to the svg tag.
+
+Scaling
+-------
+
+`x_scale, y_scale, include_x_axis`
+
+
+Indicate a hint for the scale computation:
+
+.. pygal-code::
+
+  chart = pygal.Line()
+  chart.add('line', [.0002, .0005, .00035])
+
+.. pygal-code::
+
+  chart = pygal.Line(y_scale=.0001)
+  chart.add('line', [.0002, .0005, .00035])
+
+
+You may want to always have the absissa in your graph:
+
+.. pygal-code::
+
+  chart = pygal.Line(y_scale=.0001, include_x_axis=True)
+  chart.add('line', [.0002, .0005, .00035])
+
+
+Title
+-----
+
+`title`
+
+You can add a title to the chart by setting the title option:
+
+.. pygal-code::
+
+  chart = pygal.Line(title=u'Some points')
+  chart.add('line', [.0002, .0005, .00035])
+
+
+Labels
+------
+
+`x_labels, y_labels`
+
+You can specify x labels and y labels, depending on the graph type:
+
+.. pygal-code::
+
+  chart = pygal.Line()
+  chart.x_labels = 'Red', 'Blue', 'Green'
+  chart.y_labels = .0001, .0003, .0004, .00045, .0005
+  chart.add('line', [.0002, .0005, .00035])
+
+
+Display
+-------
+
+`show_legend, show dots`
+
+You can remove legend and dots by setting these at False
+
+.. pygal-code::
+
+  chart = pygal.Line(show_legend=False)
+  chart.add('line', [.0002, .0005, .00035])
+
+
+.. pygal-code::
+
+  chart = pygal.Line(show_dots=False)
+  chart.add('line', [.0002, .0005, .00035])
+
+Rendering
+---------
+
+`fill, stroke, zero`
+
+You can disable line stroking:
+
+.. pygal-code::
+
+  chart = pygal.Line(stroke=False)
+  chart.add('line', [.0002, .0005, .00035])
+
+And enable line filling:
+
+.. pygal-code::
+
+  chart = pygal.Line(fill=True)
+  chart.add('line', [.0002, .0005, .00035])
+
+To fill to an other reference than zero:
+
+.. pygal-code::
+
+  chart = pygal.Line(fill=True, zero=.0004)
+  chart.add('line', [.0002, .0005, .00035])
+
+
+Font sizes
+----------
+
+`label_font_size, value_font_size, tooltip_font_size, title_font_size, legend_font_size`
+
+
+Set the various font size
+
+.. pygal-code::
+
+  chart = pygal.Line(label_font_size=34, legend_font_size=8)
+  chart.add('line', [0, .0002, .0005, .00035])
+
+
+Label rotation
+--------------
+
+`x_label_rotation, y_label_rotation`
+
+
+Allow label rotation (in degrees) to avoid axis cluttering:
+
+.. pygal-code::
+
+  chart = pygal.Line()
+  chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !']
+  chart.add('line', [0, .0002, .0005, .00035])
+
+
+.. pygal-code::
+
+  chart = pygal.Line(x_label_rotation=20)
+  chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !']
+  chart.add('line', [0, .0002, .0005, .00035])
+
+
+Human readable
+--------------
+
+`human_readable`
+
+
+Display values in human readable form:
+
+1 230 000 -> 1.23M
+.00 098 7 -> 987µ
+
+.. pygal-code::
+
+  chart = pygal.Line(human_readable=True, y_scale=.0001)
+  chart.add('line', [0, .0002, .0005, .00035])
+
+
+No data text
+------------
+
+`no_data_text`
+
+
+Text to display instead of the graph when no data is supplied:
+
+.. pygal-code::
+
+  chart = pygal.Line()
+  chart.add('line', [])
+
+.. pygal-code::
+
+  chart = pygal.Line(no_data_text='No result found')
+  chart.add('line', [])
--- a/pages/documentation.rst
+++ b/pages/documentation.rst
@ -6,12 +6,15 @@
 User documentation
 ==================

- `First steps </first_steps>`_
- `Charts types </chart_types>`_
- `Styles </styles>`_
+- `First steps </first_steps>`_ - learn how to very simply make beautiful charts.
+- `Charts types </chart_types>`_ - see what pygal can do for you.
+- `Styles </styles>`_ - change the style.
+- `Basic customizations </basic_customizations>`_ - start to improve your chats.
+- `Interpolations </interpolations>`_ - smooth your lines.
+- `Other customizations </other_customizations>`_ - customize all the things.


 Developper documentation
 ========================

-*TODO*
+- `Create a chart type </chart_creation>`_ - extend pygal.
--- a/pages/interpolations.rst
+++ b/pages/interpolations.rst
@ -0,0 +1,76 @@
+===============
+ Documentation
+===============
+
+
+Interpolations
+==============
+
+
+.. contents::
+
+Interpolations need the `scipy python module <http://www.scipy.org/>`_.
+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 <http://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.interp1d.html#scipy.interpolate.interp1d>`_
+
+
+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])
--- a/pages/other_customizations.rst
+++ 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.
+
+