From b01dedcedd79484920aab34869ff72901b4580a9 Mon Sep 17 00:00:00 2001 From: Florian Mounier Date: Tue, 25 Jun 2013 16:12:06 +0200 Subject: [PATCH] Add a lot of doc --- pages/basic_customizations.rst | 259 +++++++++++++++++++++++++++++---- pages/builtin_styles.rst | 206 ++++++++++++++++++++++++++ pages/chart_types.rst | 35 +++-- pages/custom_styles.rst | 116 +++++++++++++++ pages/documentation.rst | 8 +- pages/first_steps.rst | 2 + pages/home.rst | 20 +-- pages/interpolations.rst | 3 + pages/metadata.rst | 6 +- pages/other_customizations.rst | 8 + pages/parametric_styles.rst | 174 ++++++++++++++++++++++ pages/sparks.rst | 80 ++++++++++ pages/styles.rst | 196 +------------------------ pages/web.rst | 78 ++++++++++ 14 files changed, 936 insertions(+), 255 deletions(-) create mode 100644 pages/builtin_styles.rst create mode 100644 pages/custom_styles.rst create mode 100644 pages/parametric_styles.rst create mode 100644 pages/sparks.rst create mode 100644 pages/web.rst diff --git a/pages/basic_customizations.rst b/pages/basic_customizations.rst index 2e9ad51..99fa638 100644 --- a/pages/basic_customizations.rst +++ b/pages/basic_customizations.rst @@ -30,7 +30,7 @@ pygal is customized with the help of the `Config` class (see `config.py `_ +You can add a title to the x axis by setting the `x_title` option: .. pygal-code:: - chart = pygal.Line(title=u'Some different points') + chart = pygal.Line(title=u'Some points', x_title='X Axis') + chart.add('line', [.0002, .0005, .00035]) + + +Y title +~~~~~~~ + +``y_title`` + +You can add a title to the y axis by setting the `y_title` option: + +.. pygal-code:: + + chart = pygal.Line(title=u'Some points', y_title='Y Axis') + chart.add('line', [.0002, .0005, .00035]) + + +Font size +~~~~~~~~~ + +``title_font_size`` + +.. pygal-code:: + + chart = pygal.Line(title=u'Some points', x_title='X Axis', y_title='Y Axis', + title_font_size=24) chart.add('line', [.0002, .0005, .00035]) - chart.add('other line', [1000, 2000, 7000], secondary=True) Labels ------ Add labels -^^^^^^^^^^ +~~~~~~~~~~ ``x_labels, y_labels`` @@ -177,8 +231,21 @@ You can specify x labels and y labels, depending on the graph type: chart.add('line', [.0002, .0005, .00035]) +Remove y labels +~~~~~~~~~~~~~~~ + +``show_y_labels`` + +Set this to False to deactivate y labels: + +.. pygal-code:: + + chart = pygal.Line(show_y_labels=False) + chart.add('line', [.0002, .0005, .00035]) + + Rotate labels -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ ``x_label_rotation, y_label_rotation`` @@ -188,19 +255,27 @@ Allow label rotation (in degrees) to avoid axis cluttering: .. pygal-code:: chart = pygal.Line() - chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !'] + chart.x_labels = [ + 'This is the first point !', + 'This is the second point !', + 'This is the third point !', + 'This is the fourth point !'] chart.add('line', [0, .0002, .0005, .00035]) .. pygal-code:: chart = pygal.Line(x_label_rotation=20) - chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !'] + chart.x_labels = [ + 'This is the first point !', + 'This is the second point !', + 'This is the third point !', + 'This is the fourth point !'] chart.add('line', [0, .0002, .0005, .00035]) Change minor/major labels -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ ``x_labels_major, x_labels_major_every, x_labels_major_count, show_minor_x_labels`` @@ -209,7 +284,11 @@ You can alter major minor behaviour for the abscissa thanks to `Arjen Stolk `_ + +.. pygal-code:: + + chart = pygal.Line(title=u'Some different points') + chart.add('line', [.0002, .0005, .00035]) + chart.add('other line', [1000, 2000, 7000], secondary=True) + + Rendering --------- @@ -299,7 +493,7 @@ To fill to an other reference than zero: Font sizes ---------- -``label_font_size, value_font_size, tooltip_font_size, title_font_size, legend_font_size`` +``value_font_size, tooltip_font_size`` Set the various font size @@ -323,7 +517,11 @@ You can override that by setting truncation lenght with `truncate_legend` and `t .. pygal-code:: chart = pygal.Line(truncate_legend=3, truncate_label=17) - chart.x_labels = ['This is the first point !', 'This is the second point !', 'This is the third point !', 'This is the fourth point !'] + chart.x_labels = [ + 'This is the first point !', + 'This is the second point !', + 'This is the third point !', + 'This is the fourth point !'] chart.add('line', [0, .0002, .0005, .00035]) @@ -361,3 +559,6 @@ Text to display instead of the graph when no data is supplied: chart = pygal.Line(no_data_text='No result found') chart.add('line', []) + + +Next: `Interpolations `_ diff --git a/pages/builtin_styles.rst b/pages/builtin_styles.rst new file mode 100644 index 0000000..ad9fa98 --- /dev/null +++ b/pages/builtin_styles.rst @@ -0,0 +1,206 @@ +=============== + Documentation +=============== + + +Built-in Styles +=============== + +pygal provides 14 built-in styles: + +.. contents:: + + +Default +------- + +.. pygal-code:: + + chart = pygal.StackedLine(fill=True, interpolate='cubic') + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Neon +---- + +.. pygal-code:: + + from pygal.style import NeonStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=NeonStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Dark Solarized +-------------- + +.. pygal-code:: + + from pygal.style import DarkSolarizedStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkSolarizedStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Light Solarized +--------------- + +.. pygal-code:: + + from pygal.style import LightSolarizedStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightSolarizedStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Light +----- + +.. pygal-code:: + + from pygal.style import LightStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Clean +----- + +.. pygal-code:: + + from pygal.style import CleanStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=CleanStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Red Blue +-------- + +.. pygal-code:: + + from pygal.style import RedBlueStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=RedBlueStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Dark Colorized +-------------- + +.. pygal-code:: + + from pygal.style import DarkColorizedStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkColorizedStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Light Colorized +--------------- + +.. pygal-code:: + + from pygal.style import LightColorizedStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightColorizedStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Turquoise +--------- + +.. pygal-code:: + + from pygal.style import TurquoiseStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=TurquoiseStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Light green +----------- + +.. pygal-code:: + + from pygal.style import LightGreenStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightGreenStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Dark green +---------- + +.. pygal-code:: + + from pygal.style import DarkGreenStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkGreenStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Dark green blue +--------------- + +.. pygal-code:: + + from pygal.style import DarkGreenBlueStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkGreenBlueStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Blue +---- + +.. pygal-code:: + + from pygal.style import BlueStyle + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=BlueStyle) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) diff --git a/pages/chart_types.rst b/pages/chart_types.rst index 69cd3dd..17788d0 100644 --- a/pages/chart_types.rst +++ b/pages/chart_types.rst @@ -14,7 +14,7 @@ Line charts ----------- Basic -^^^^^ +~~~~~ Basic simple line graph: @@ -29,7 +29,7 @@ Basic simple line graph: line_chart.add('Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4, 8.9, 5.8, 6.7, 6.8, 7.5]) Stacked -^^^^^^^ +~~~~~~~ Same graph but with stacked values and filled rendering: @@ -48,7 +48,7 @@ Bar charts / Histograms ----------------------- Basic -^^^^^ +~~~~~ Basic simple bar graph: @@ -64,7 +64,7 @@ Basic simple bar graph: Stacked -^^^^^^^ +~~~~~~~ Same graph but with stacked values: @@ -80,7 +80,7 @@ Same graph but with stacked values: Horizontal -^^^^^^^^^^ +~~~~~~~~~~ Horizontal bar diagram: @@ -99,7 +99,7 @@ XY charts --------- Basic -^^^^^ +~~~~~ Basic XY lines, drawing cosinus: @@ -117,7 +117,7 @@ Basic XY lines, drawing cosinus: Scatter Plot -^^^^^^^^^^^^ +~~~~~~~~~~~~ Disabling stroke make a good scatter plot @@ -131,7 +131,7 @@ Disabling stroke make a good scatter plot DateY -^^^^^ +~~~~~ You can index values by dates (Thanks to `Snarkturne `_) .. pygal-code:: @@ -151,7 +151,7 @@ Pies ---- Basic -^^^^^ +~~~~~ Simple pie: @@ -168,7 +168,7 @@ Simple pie: Multi-series pie -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ Same pie but divided in sub category: @@ -187,7 +187,7 @@ Radar charts ------------ Basic -^^^^^ +~~~~~ Simple Kiviat diagram: @@ -206,7 +206,7 @@ Dot charts ---------- Basic -^^^^^ +~~~~~ Punch card like chart: @@ -225,7 +225,7 @@ Funnel charts ------------- Basic -^^^^^ +~~~~~ Funnel chart: @@ -243,7 +243,7 @@ Gauge charts ------------ Basic -^^^^^ +~~~~~ Simple gauge chart: @@ -263,7 +263,7 @@ Pyramid charts -------------- Basic -^^^^^ +~~~~~ Population pyramid: @@ -294,7 +294,7 @@ Worldmap charts --------------- Basic -^^^^^ +~~~~~ Highlight some countries: @@ -524,3 +524,6 @@ The following countries are supported: - `za`: South Africa - `zm`: Zambia - `zw`: Zimbabwe + + +Next: `Styles `_ diff --git a/pages/custom_styles.rst b/pages/custom_styles.rst new file mode 100644 index 0000000..3c7a31a --- /dev/null +++ b/pages/custom_styles.rst @@ -0,0 +1,116 @@ +=============== + Documentation +=============== + + +Custom Styles +============= + +pygal provides 2 ways to customize styles: + +.. contents:: + + +Using Style class +----------------- + +You can instantiate the `Style` class with some customizations for quick styling: + +.. pygal-code:: + + from pygal.style import Style + custom_style = Style( + background='transparent', + plot_background='transparent', + foreground='#53E89B', + foreground_light='#53A0E8', + foreground_dark='#630C0D', + opacity='.6', + opacity_hover='.9', + transition='400ms ease-in', + colors=('#E853A0', '#E8537A', '#E95355', '#E87653', '#E89B53')) + + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=custom_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Using a custom css +------------------ + +You can also specify a file containing a custom css for more customization. The css option is an array containing included css by default (except from ``base.css`` which is always included). + +It supports local file names and external stylesheet too, just append your URI in the list. + +(See the `default css `_) + +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/pages/documentation.rst b/pages/documentation.rst index 5cce8e4..b63a3d8 100644 --- a/pages/documentation.rst +++ b/pages/documentation.rst @@ -11,11 +11,7 @@ User documentation - `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. - - -Developer documentation -======================= - -- `Create a chart type `_ - extend pygal. +- `Embedding in a web page `_ - see several ways to use pygal on the intertubes. diff --git a/pages/first_steps.rst b/pages/first_steps.rst index 8e128a4..a1492e0 100644 --- a/pages/first_steps.rst +++ b/pages/first_steps.rst @@ -64,3 +64,5 @@ And finally add a title and some labels: bar_chart.add('Fibonacci', [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]) bar_chart.add('Padovan', [1, 1, 1, 2, 2, 3, 4, 5, 7, 9, 12]) + +Next: `Charts types `_ diff --git a/pages/home.rst b/pages/home.rst index 67b074c..3285078 100644 --- a/pages/home.rst +++ b/pages/home.rst @@ -64,24 +64,26 @@ It features various graph types: -Python/Css styling with some packaged themes (`default `_, -`light `_, -`neon `_, -`clean `_, -`dark_solarized `_, -`light_solarized `_) +Python/Css styling with some pre-defined themes. See `styling `_. -`And a lot of options to customize the charts. `_ +And a lot of options to `customize the charts. `_ Get it ! ======== -- `Get the package on pypi `_ -- `Fork me on github `_ +- 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 ===================== diff --git a/pages/interpolations.rst b/pages/interpolations.rst index 396c845..df91df9 100644 --- a/pages/interpolations.rst +++ b/pages/interpolations.rst @@ -74,3 +74,6 @@ You can change the resolution of the interpolation with the help of `interpolati chart = pygal.Line(interpolate='krogh', interpolation_precision=50) chart.add('line', [1, 5, 17, 12, 5, 10]) + + +Next: `Sparklines `_ diff --git a/pages/metadata.rst b/pages/metadata.rst index 8a46096..9d01896 100644 --- a/pages/metadata.rst +++ b/pages/metadata.rst @@ -28,7 +28,7 @@ Links ----- Basic -^^^^^ +~~~~~ You can also add hyper links: @@ -58,7 +58,7 @@ You can also add hyper links: Advanced -^^^^^^^^ +~~~~~~~~ You can specify a dictionary to xlink with all links attributes: @@ -96,4 +96,4 @@ You can specify a dictionary to xlink with all links attributes: }]) - +Next: `Other customizations `_ diff --git a/pages/other_customizations.rst b/pages/other_customizations.rst index 0e57fe4..c1fa58d 100644 --- a/pages/other_customizations.rst +++ b/pages/other_customizations.rst @@ -112,3 +112,11 @@ this option disables the xml prolog in the output. Since no encoding is declared, the result will be in unicode instead of bytes. + +No prefix +--------- + +``no_prefix`` + +Normally pygal set an unique id to the chart and use it to style each chart to avoid collisions when svg are directly embedded in html. This can be a problem if you use external styling overriding the prefixed css. You can set this to True in order to prevent that behaviour. + diff --git a/pages/parametric_styles.rst b/pages/parametric_styles.rst new file mode 100644 index 0000000..c0995e8 --- /dev/null +++ b/pages/parametric_styles.rst @@ -0,0 +1,174 @@ +=============== + Documentation +=============== + + +Parametric Styles +================= + +pygal provides 5 parametric styles: + +.. contents:: + + +Usage +----- + +A parametric style is initiated with a default color and the other are generated from this one: + +.. pygal-code:: + + from pygal.style import LightenStyle + dark_lighten_style = LightenStyle('#336676') + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +You can set the `step` parameter to tell between how much colors the color modifier will be applied + +.. pygal-code:: + + from pygal.style import LightenStyle + dark_lighten_style = LightenStyle('#336676', step=5) + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + +and the `max_` to limit the amplitude at a certain value (in % for all color operation except rotate which is 360): + +.. pygal-code:: + + from pygal.style import LightenStyle + dark_lighten_style = LightenStyle('#336676', step=5, max_=10) + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +You can tell the style to inheritate all the styles from another theme: + +.. pygal-code:: + + from pygal.style import LightenStyle, LightColorizedStyle + dark_lighten_style = LightenStyle('#336676', base_style=LightColorizedStyle) + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +And you can manually set the properties just like any other theme: + +.. pygal-code:: + + from pygal.style import LightenStyle, LightColorizedStyle + dark_lighten_style = LightenStyle('#336676', base_style=LightColorizedStyle) + dark_lighten_style.background = '#ffcccc' + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Styles +------ + + +Rotate +~~~~~~ + +.. pygal-code:: + + from pygal.style import RotateStyle + dark_rotate_style = RotateStyle('#9e6ffe') + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_rotate_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + +.. pygal-code:: + + from pygal.style import RotateStyle, LightColorizedStyle + dark_rotate_style = RotateStyle('#75ff98', base_style=LightColorizedStyle) + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_rotate_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Lighten +~~~~~~~ + +.. pygal-code:: + + from pygal.style import LightenStyle + dark_lighten_style = LightenStyle('#004466') + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=dark_lighten_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Darken +~~~~~~ + +.. pygal-code:: + + from pygal.style import DarkenStyle + darken_style = DarkenStyle('#ff8723') + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=darken_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Saturate +~~~~~~~~ + +.. pygal-code:: + + from pygal.style import SaturateStyle + saturate_style = SaturateStyle('#609f86') + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=saturate_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) + + +Desaturate +~~~~~~~~~~ + +.. pygal-code:: + + from pygal.style import DesaturateStyle + desaturate_style = DesaturateStyle('#8322dd') + chart = pygal.StackedLine(fill=True, interpolate='cubic', style=desaturate_style) + chart.add('A', [1, 3, 5, 16, 13, 3, 7]) + chart.add('B', [5, 2, 3, 2, 5, 7, 17]) + chart.add('C', [6, 10, 9, 7, 3, 1, 0]) + chart.add('D', [2, 3, 5, 9, 12, 9, 5]) + chart.add('E', [7, 4, 2, 1, 2, 10, 0]) diff --git a/pages/sparks.rst b/pages/sparks.rst new file mode 100644 index 0000000..01274bd --- /dev/null +++ b/pages/sparks.rst @@ -0,0 +1,80 @@ +=============== + Documentation +=============== + + +Sparklines +========== + +pygal provides a simple way to get beautiful sparklines. + + +.. contents:: + + +Basic +----- + +.. pygal-code:: True + + chart = pygal.Line() + chart.add('', [1, 3, 5, 16, 13, 3, 7]) + chart.render_sparkline() + + +Styles +------ + +It supports styling like any chart but the option is given to the `render_sparkline` method: + +.. pygal-code:: sparkline + + from pygal.style import DarkSolarizedStyle + chart = pygal.Line() + chart.add('', [1, 3, 5, 16, 13, 3, 7]) + chart.render_sparkline(style=DarkSolarizedStyle) + + +Options +------- + +It's the same for other options: + +.. pygal-code:: sparkline + + chart = pygal.Line() + chart.add('', [1, 3, 5, 16, 13, 3, 7]) + chart.render_sparkline(interpolate='cubic') + +.. pygal-code:: sparkline + + chart = pygal.Line() + chart.add('', [1, 3, 5, 16, 13, 3, 7, 9, 2, 1, 4, 9, 12, 10, 12, 16, 14, 12, 7, 2]) + chart.render_sparkline(width=500, height=25, show_dots=True) + + +Sparktext +--------- + +If you want to get a simple spartext, use the render_sparktext function: + +.. code-block:: python + + chart = pygal.Line() + chart.add('', [1, 3, 5, 16, 13, 3, 7]) + chart.render_sparktext() + +→ `▁▁▂█▆▁▃` + +You can also specify an explicit minimum for the values: + +.. code-block:: python + + chart = pygal.Line() + chart.add('', [1, 3, 5, 16, 13, 3, 7]) + chart.render_sparktext(relative_to=0) + +→ `▁▂▃█▆▂▄` + + +Next: `Metadata `_ diff --git a/pages/styles.rst b/pages/styles.rst index da772c9..0615325 100644 --- a/pages/styles.rst +++ b/pages/styles.rst @@ -2,196 +2,8 @@ Documentation =============== +There are three ways to style the charts: -Styles -====== - -pygal provides 6 different styles and 2 ways to add your own: - -.. contents:: - - -Default -------- - -.. pygal-code:: - - chart = pygal.StackedLine(fill=True, interpolate='cubic') - chart.add('A', [1, 3, 5, 16, 13, 3, 7]) - chart.add('B', [5, 2, 3, 2, 5, 7, 17]) - chart.add('C', [6, 10, 9, 7, 3, 1, 0]) - chart.add('D', [2, 3, 5, 9, 12, 9, 5]) - chart.add('E', [7, 4, 2, 1, 2, 10, 0]) - - -Neon ----- - -.. pygal-code:: - - from pygal.style import NeonStyle - chart = pygal.StackedLine(fill=True, interpolate='cubic', style=NeonStyle) - chart.add('A', [1, 3, 5, 16, 13, 3, 7]) - chart.add('B', [5, 2, 3, 2, 5, 7, 17]) - chart.add('C', [6, 10, 9, 7, 3, 1, 0]) - chart.add('D', [2, 3, 5, 9, 12, 9, 5]) - chart.add('E', [7, 4, 2, 1, 2, 10, 0]) - - -Dark Solarized --------------- - -.. pygal-code:: - - from pygal.style import DarkSolarizedStyle - chart = pygal.StackedLine(fill=True, interpolate='cubic', style=DarkSolarizedStyle) - chart.add('A', [1, 3, 5, 16, 13, 3, 7]) - chart.add('B', [5, 2, 3, 2, 5, 7, 17]) - chart.add('C', [6, 10, 9, 7, 3, 1, 0]) - chart.add('D', [2, 3, 5, 9, 12, 9, 5]) - chart.add('E', [7, 4, 2, 1, 2, 10, 0]) - - -Light Solarized ---------------- - -.. pygal-code:: - - from pygal.style import LightSolarizedStyle - chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightSolarizedStyle) - chart.add('A', [1, 3, 5, 16, 13, 3, 7]) - chart.add('B', [5, 2, 3, 2, 5, 7, 17]) - chart.add('C', [6, 10, 9, 7, 3, 1, 0]) - chart.add('D', [2, 3, 5, 9, 12, 9, 5]) - chart.add('E', [7, 4, 2, 1, 2, 10, 0]) - - -Light ------ - -.. pygal-code:: - - from pygal.style import LightStyle - chart = pygal.StackedLine(fill=True, interpolate='cubic', style=LightStyle) - chart.add('A', [1, 3, 5, 16, 13, 3, 7]) - chart.add('B', [5, 2, 3, 2, 5, 7, 17]) - chart.add('C', [6, 10, 9, 7, 3, 1, 0]) - chart.add('D', [2, 3, 5, 9, 12, 9, 5]) - chart.add('E', [7, 4, 2, 1, 2, 10, 0]) - - -Clean ------ - -.. pygal-code:: - - from pygal.style import CleanStyle - chart = pygal.StackedLine(fill=True, interpolate='cubic', style=CleanStyle) - chart.add('A', [1, 3, 5, 16, 13, 3, 7]) - chart.add('B', [5, 2, 3, 2, 5, 7, 17]) - chart.add('C', [6, 10, 9, 7, 3, 1, 0]) - chart.add('D', [2, 3, 5, 9, 12, 9, 5]) - chart.add('E', [7, 4, 2, 1, 2, 10, 0]) - - -Custom ------- - -You can customize styles in two ways: - -Using Style class -^^^^^^^^^^^^^^^^^ - -You can instantiate the `Style` class with some customizations for quick styling: - -.. pygal-code:: - - from pygal.style import Style - custom_style = Style( - background='transparent', - plot_background='transparent', - foreground='#53E89B', - foreground_light='#53A0E8', - foreground_dark='#630C0D', - opacity='.6', - opacity_hover='.9', - transition='400ms ease-in', - colors=('#E853A0', '#E8537A', '#E95355', '#E87653', '#E89B53')) - - chart = pygal.StackedLine(fill=True, interpolate='cubic', style=custom_style) - chart.add('A', [1, 3, 5, 16, 13, 3, 7]) - chart.add('B', [5, 2, 3, 2, 5, 7, 17]) - chart.add('C', [6, 10, 9, 7, 3, 1, 0]) - chart.add('D', [2, 3, 5, 9, 12, 9, 5]) - chart.add('E', [7, 4, 2, 1, 2, 10, 0]) - - -Using a custom css -^^^^^^^^^^^^^^^^^^ - -You can also specify a file containing a custom css for more customization. The css option is an array containing included css by default (except from ``base.css`` which is always included). - -It supports local file names and external stylesheet too, just append your URI in the list. - -(See the `default css `_) - -.. pygal-code:: - - from tempfile import NamedTemporaryFile - custom_css = ''' - text { - fill: green; - font-family: monospace; - } - .legends .legend text { - font-size: {{ font_sizes.legend }}; - } - .axis { - stroke: #666; - } - .axis text { - font-size: {{ font_sizes.label }}; - font-family: sans; - stroke: none; - } - .axis.y text { - text-anchor: end; - } - #tooltip text { - font-size: {{ font_sizes.tooltip }}; - } - .dot { - fill: yellow; - } - .color-0 { - stroke: #ff1100; - fill: #ff1100; - } - .color-1 { - stroke: #ffee00; - fill: #ffee00; - } - .color-2 { - stroke: #66bb44; - fill: #66bb44; - } - .color-3 { - stroke: #88bbdd; - fill: #88bbdd; - } - .color-4 { - stroke: #0000ff; - fill: #0000ff; - } - ''' - custom_css_file = '/tmp/pygal_custom_style.css' - with open(custom_css_file, 'w') as f: - f.write(custom_css) - config = pygal.Config(fill=True, interpolate='cubic') - config.css.append(custom_css_file) - chart = pygal.StackedLine(config) - chart.add('A', [1, 3, 5, 16, 13, 3, 7]) - chart.add('B', [5, 2, 3, 2, 5, 7, 17]) - chart.add('C', [6, 10, 9, 7, 3, 1, 0]) - chart.add('D', [2, 3, 5, 9, 12, 9, 5]) - chart.add('E', [7, 4, 2, 1, 2, 10, 0]) +- Using `built-in themes `_ +- Using `parametric themes `_ +- Using `custom themes `_ diff --git a/pages/web.rst b/pages/web.rst new file mode 100644 index 0000000..acc43b4 --- /dev/null +++ b/pages/web.rst @@ -0,0 +1,78 @@ +=============== + Documentation +=============== + + +Embedding in a web page +======================= + +.. contents:: + + +Within an embed tag +------------------- + +First setup an url entry point for you svg: `/mysvg.svg` don't forget to set the mime-type to `image/svg+xml`. (If you are using flask you can use the `render_response` method.) + +Then in your html put an embed tag like this: + +.. code-block:: html + + + + + + + +
+ +
+ + + +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. +