Update documentation to v1.0.0

12 years ago · 0b5a17d749
6 changed files with 413 additions and 30 deletions
--- a/configuration.yaml
+++ b/configuration.yaml
@ -31,7 +31,6 @@ code browser (github):
  project name: Kozea/pygal

 bug tracker (github):
-  base url: http://github.com/Kozea/pygal/issues
  project name: Kozea/pygal

 continuous integration (jenkins):
--- a/news/fmounier/2013-06-06@12:00:00.rst
+++ b/news/fmounier/2013-06-06@12:00:00.rst
@ -0,0 +1,55 @@
+Pygal 1.0.0
+===========
+
+
+Time to become 1.0 !
+
+Get it via `PyPi <http://pypi.python.org/pypi/pygal/>`_.
+
+
+Changelog
+---------
+
+- pygal is now python 2.6, 2.7, 3.2, 3.3 fully compatible without the use of `2to3`.
+
+- `Secondary axes <basic_customizations/#two-y-axes>`_
+
+.. 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)
+
+
+- New graph types:
+
+  + `DateY </chart_types/#datey>`_ for date indexed XY charts
+  + `Worldmap </chart_types/#worldmap-charts>`_ for a beautifull worldmap
+
+
+.. 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
+  })
+
--- a/pages/basic_customizations.rst
+++ b/pages/basic_customizations.rst
@ -111,6 +111,27 @@ You may want to always have the absissa in your graph:
  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])
+
+
+
 Title
 -----

@ -124,9 +145,26 @@ You can add a title to the chart by setting the `title` option:
  chart.add('line', [.0002, .0005, .00035])


+Two y axes
+----------
+
+``secondary``
+
+You can plot your values to 2 separate axes, thanks to `wiktorn <https://github.com/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)
+
+
 Labels
 ------

+Add labels
+^^^^^^^^^^
+
 ``x_labels, y_labels``

 You can specify x labels and y labels, depending on the graph type:
@ -139,6 +177,65 @@ You can specify x labels and y labels, depending on the graph type:
  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``
+
+You can alter major minor behaviour for the abscissa thanks to `Arjen Stolk <https://github.com/simplyarjen>`_
+
+.. 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])
+
+
 Display
 -------

@ -213,28 +310,6 @@ Set the various font size
  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])
-
-
 Text truncation
 ---------------

--- a/pages/chart_types.rst
+++ b/pages/chart_types.rst
@ -6,7 +6,7 @@
 Chart types
 ===========

-pygal provides 9 kind of charts:
+pygal provides 10 kind of charts:

 .. contents::

@ -130,6 +130,23 @@ Disabling stroke make a good scatter plot
  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 <https://github.com/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)
+  ])
+
+
+
 Pies
 ----

@ -272,3 +289,238 @@ Population pyramid:
  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
+    - `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
--- a/pages/documentation.rst
+++ b/pages/documentation.rst
@ -9,7 +9,7 @@ User documentation
 - `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.
+- `Basic customizations </basic_customizations>`_ - start to improve your charts.
 - `Interpolations </interpolations>`_ - smooth your lines.
 - `Metadata </metadata>`_ - enrich your graph.
 - `Other customizations </other_customizations>`_ - customize all the things.
--- a/pages/home.rst
+++ b/pages/home.rst
@ -5,7 +5,7 @@
 Presentation
 ============

-pygal is a dynamic SVG charting library.
+pygal 1.0 is a dynamic SVG charting library.


 .. class:: thumbs
@ -60,6 +60,8 @@ It features various graph types:

 - `Gauge charts </chart_types/#gauge-charts>`_

+- `Worldmap charts </chart_types/#worldmap-charts>`_
+


 Python/Css styling with some packaged themes (`default </styles/#default>`_,
@ -83,7 +85,7 @@ More information in the `download page </download>`_
 Technical Description
 =====================

-As of now pygal is known to work for python 2.6, 2.7 and 3.2.
+As of now pygal is known to work for python 2.6, 2.7 and 3.2, 3.3.


 Needed dependencies