Serie and value configuration doc

10 years ago · 2672cd3c38
8 changed files with 192 additions and 42 deletions
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@ -12,7 +12,7 @@ Submit your bug reports and feature requests to the `github bug tracker <http://
 Code style
 ==========

-The pygal code tries to respect the `pep8 <https://www.python.org/dev/peps/pep-0008/>`_ please keep that in mind when writing code for pygal. (The code style is checked along witht the unit tests, see next paragraph).
+The pygal code tries to respect the `pep8 <https://www.python.org/dev/peps/pep-0008/>`_ please keep that in mind when writing code for pygal. (The code style is checked along with the unit tests, see next paragraph).


 Testing
--- a/docs/documentation/configuration/chart.rst
+++ b/docs/documentation/configuration/chart.rst
@ -75,6 +75,7 @@ Options

 .. toctree::
   :maxdepth: 2
+
   sizing
   title
   label
--- a/docs/documentation/configuration/serie.rst
+++ b/docs/documentation/configuration/serie.rst
@ -13,17 +13,102 @@ Series are customized using keyword args set in the ``add`` function:
   chart.add([3, 2, 1], dot=False)


+
 Options
 -------

+.. contents::
+   :local:
+

 secondary
 ~~~~~~~~~

 You can plot your values to 2 separate axes, thanks to `wiktorn <https://github.com/wiktorn>`_
+This is the only serie only option.

 .. pygal-code::

  chart = pygal.Line(title=u'Some different points')
+  chart.x_labels = ('one', 'two', 'three')
  chart.add('line', [.0002, .0005, .00035])
  chart.add('other line', [1000, 2000, 7000], secondary=True)
+
+
+stroke
+~~~~~~
+
+.. 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)])
+  xy_chart.add('Correl', [(0, 0), (2.8, 2.4)], stroke=True)
+
+
+fill
+~~~~
+
+.. pygal-code::
+
+  chart = pygal.Line()
+  chart.add('line', [.0002, .0005, .00035], fill=True)
+  chart.add('line', [.0004, .0009, .001])
+
+
+show_dots
+~~~~~~~~~
+
+.. pygal-code::
+
+  chart = pygal.Line()
+  chart.add('line', [.0002, .0005, .00035], show_dots=False)
+  chart.add('line', [.0004, .0009, .001])
+
+
+show_only_major_dots
+~~~~~~~~~~~~~~~~~~~~
+
+
+.. pygal-code::
+
+  chart = pygal.Line()
+  chart.add('line', range(12))
+  chart.add('line', range(12)[::-1], show_only_major_dots=True)
+  chart.x_labels = map(str, range(12))
+  chart.x_labels_major = ['2', '4', '8', '11']
+
+
+dots_size
+~~~~~~~~~
+
+
+.. pygal-code::
+
+  chart = pygal.Line()
+  chart.add('line', [.0002, .0005, .00035], dots_size=4)
+  chart.add('line', [.0004, .0009, .001], dots_size=12)
+
+
+rounded_bars
+~~~~~~~~~~~~
+
+
+.. pygal-code::
+
+   chart = pygal.Bar()
+   for i in range(10):
+     chart.add(str(i), i, rounded_bars=2 * i)
+
+
+inner_radius
+~~~~~~~~~~~~
+
+
+.. pygal-code::
+
+   chart = pygal.Pie()
+   for i in range(10):
+     chart.add(str(i), i, inner_radius=(10 - i) / 10)
--- a/docs/documentation/configuration/value.rst
+++ b/docs/documentation/configuration/value.rst
@ -1,6 +1,17 @@
 Value configuration
 ===================

+How
+---
+
+Values are customized by replacing the value with a dictionary containing the value as 'value':
+
+.. code-block:: python
+
+   chart = pygal.Line()
+   chart.add([1, {'value': 2, 'label': 'two'}, 3])
+   chart.add([3, 2, 1])
+

 Labels
 ------
@ -10,11 +21,54 @@ You can add per value metadata like labels, by specifying a dictionary instead o
 .. 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'}])
+  chart.add('First', [{'value': 2, 'label': 'This is the first'}])
+  chart.add('Second', [{'value': 4, 'label': 'This is the second'}])
+  chart.add('Third', 7)
+  chart.add('Fourth', [{'value': 5}])
+  chart.add('Fifth', [{'value': 3, 'label': 'This is the fifth'}])
+
+
+Style
+-----
+
+You can force the color of a value by specifying a color key:
+
+.. pygal-code::
+
+  chart = pygal.Bar()
+  chart.add('Serie', [
+   {'value': 2}, 3, 4,
+   {'value': 10, 'color': 'red'},
+   {'value': 11, 'color': 'rgba(255, 45, 20, .6)'}, 4, 2
+  ])
+
+The color key set the fill and the stroke style. You can also set the css style manually:
+
+.. pygal-code::
+
+  chart = pygal.Bar()
+  chart.add('Serie', [
+   {'value': 2}, 3, 4,
+   {'value': 10, 'style': 'fill: red; stroke: black; stroke-width: 4'},
+   {'value': 11, 'style': 'fill: rgba(255, 45, 20, .6); stroke: black; stroke-dasharray: 15, 10, 5, 10, 15'},
+   4, 2
+  ])
+
+
+Node attributes
+---------------
+
+It is possible to pass svg attribute to the node representing value.
+
+.. pygal-code::
+
+  chart = pygal.Line()
+  chart.add('Serie', [
+    {'value': 1, 'node': {'r': 2}},
+    {'value': 2, 'node': {'r': 4}},
+    {'value': 3, 'node': {'r': 6}},
+    {'value': 4, 'node': {'r': 8}}
+  ])


 Links
@ -28,26 +82,26 @@ You can also add hyper links:
 .. pygal-code::

  chart = pygal.Bar()
-  chart.add('Red', [{
+  chart.add('First', [{
    'value': 2,
-    'label': 'This is red',
-    'xlink': 'http://en.wikipedia.org/wiki/Red'}])
+    'label': 'This is the first',
+    'xlink': 'http://en.wikipedia.org/wiki/First'}])

-  chart.add('Green', [{
+  chart.add('Second', [{
    'value': 4,
-    'label': 'This is green',
-    'xlink': 'http://en.wikipedia.org/wiki/Green'}])
+    'label': 'This is the second',
+    'xlink': 'http://en.wikipedia.org/wiki/Second'}])

-  chart.add('Yellow', 7)
+  chart.add('Third', 7)

-  chart.add('Blue', [{
+  chart.add('Fourth', [{
    'value': 5,
-    'xlink': 'http://en.wikipedia.org/wiki/Blue'}])
+    'xlink': 'http://en.wikipedia.org/wiki/Fourth'}])

-  chart.add('Violet', [{
+  chart.add('Fifth', [{
    'value': 3,
-    'label': 'This is violet',
-    'xlink': 'http://en.wikipedia.org/wiki/Violet_(color)'}])
+    'label': 'This is the fifth',
+    'xlink': 'http://en.wikipedia.org/wiki/Fifth'}])


 Advanced
@ -58,33 +112,33 @@ You can specify a dictionary to xlink with all links attributes:
 .. pygal-code::

  chart = pygal.Bar()
-  chart.add('Red', [{
+  chart.add('First', [{
    'value': 2,
-    'label': 'This is red',
-    'xlink': {'href': 'http://en.wikipedia.org/wiki/Red'}}])
+    'label': 'This is the first',
+    'xlink': {'href': 'http://en.wikipedia.org/wiki/First'}}])

-  chart.add('Green', [{
+  chart.add('Second', [{
    'value': 4,
-    'label': 'This is green',
+    'label': 'This is the second',
    'xlink': {
-      'href': 'http://en.wikipedia.org/wiki/Green',
+      'href': 'http://en.wikipedia.org/wiki/Second',
      'target': '_top'}
    }])

-  chart.add('Yellow', 7)
+  chart.add('Third', 7)

-  chart.add('Blue', [{
+  chart.add('Fourth', [{
    'value': 5,
    'xlink': {
-      'href': 'http://en.wikipedia.org/wiki/Blue',
+      'href': 'http://en.wikipedia.org/wiki/Fourth',
      'target': '_blank'}
    }])

-  chart.add('Violet', [{
+  chart.add('Fifth', [{
    'value': 3,
-    'label': 'This is violet',
+    'label': 'This is the fifth',
    'xlink': {
-      'href': 'http://en.wikipedia.org/wiki/Violet_(color)',
+      'href': 'http://en.wikipedia.org/wiki/Fifth',
      'target': '_self'}
    }])

--- a/docs/documentation/web.rst
+++ b/docs/documentation/web.rst
@ -5,7 +5,7 @@ Embedding in a web page
 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.)
+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:

@ -23,13 +23,13 @@ Then in your html put an embed tag like this:
    </body>
  </html>

-You can also use an iframe tag, but automatic sizing with `width: 100%` will not work.
+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 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:


@ -38,7 +38,7 @@ You have to put the javascript manually in you webpage, for instance:
  <!DOCTYPE html>
  <html>
    <head>
-    <script type="text/javascript" src="http://kozea.github.com/pygal.js/latest/pygal-tooltips.js"></script>
+    <script type="text/javascript" src="http://kozea.github.com/pygal.js/latest/pygal-tooltips.min.js"></script>
      <!-- ... -->
    </head>
    <body>
@ -66,5 +66,5 @@ You have to put the javascript manually in you webpage, for instance:
    </body>
  </html>

-You can use `explicit_size` to set the svg size from the `width`, `height` properties.
+You can use ``explicit_size`` to set the svg size from the ``width``, ``height`` properties.

--- a/docs/installing.rst
+++ b/docs/installing.rst
@ -2,22 +2,36 @@
 Installing
 ==========

+pygal is available for python 2.6, 2.7 and 3.2, 3.3, 3.4 and pypy.
+
+
 PyPI
 ====

 pygal is `available on PyPI <http://pypi.python.org/pypi/pygal/>`_.
-To install, just type as superuser::
+To install, just type as superuser:

 .. code-block:: bash

  pip install pygal


+Dependencies
+============
+
+There are no required dependency.
+
+Optional dependencies are as follow:
+
+ * ``lxml`` which can improve rendering speed (except on pypy).
+ * ``cairosvg``, ``tinycss``, ``cssselect`` to render png.
+
+
 Git Repository
 ==============

 If you want the development version of pygal, take a look at the
-`git repository on GitHub <https://github.com/Kozea/pygal>`_, or clone it with::
+`git repository on GitHub <https://github.com/Kozea/pygal>`_, or clone it with:

 .. code-block:: bash

--- a/pygal/css/graph.css
+++ b/pygal/css/graph.css
@ -60,9 +60,6 @@
 {{ id }}.axis .major.guide.line {
  stroke-dasharray: 6,6;
 }
-{{ id }}.axis text.major {
-  stroke-width: .25px;
-}

 {{ id }}.horizontal .axis.y .guide.line,
 {{ id }}.horizontal .axis.y2 .guide.line,
@ -106,7 +103,7 @@
  fill: transparent;
 }

-{{ id }}.series text {
+{{ id }} text {
  stroke: none;
 }

--- a/pygal/css/style.css
+++ b/pygal/css/style.css
@ -76,7 +76,6 @@
 }

 {{ id }}.axis text.major {
-  stroke: {{ style.foreground_light }};
  fill: {{ style.foreground_light }};
 }