playground
/
pygal
mirror of https://github.com/Kozea/pygal.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

Start updating docs. + Re organize again + Include changelog

pull/242/head
Florian Mounier 9 years ago
parent
4f661e644d
commit
633bcda573
13 changed files with 230 additions and 211 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 88
      CHANGELOG
  2. 1
      CHANGELOG
  3. 9
      docs/api.rst
  4. 10
      docs/api/pygal.maps.rst
  5. 107
      docs/changelog.rst
  6. 32
      docs/contributing.rst
  7. 13
      docs/documentation/first_steps.rst
  8. 4
      docs/documentation/index.rst
  9. 20
      docs/documentation/sparks.rst
  10. 1
      docs/ext/pygal_sphinx_directives.py
  11. 108
      docs/index.rst
  12. 15
      docs/installing.rst
  13. 11
      docs/support.rst
  14. 22
      pygal/maps/__init__.py

88
CHANGELOG
Unescape View File

@ -1,88 +0,0 @@
V 2.0.0 UNRELEASED
Rework the ghost mechanism to come back to a more object oriented behavior, storing all state in a state object which is created on every render. (#161)
Refactor maps
Add world continents
Add swiss cantons map (thanks sergedroz)
Add inverse_y_axis options to reverse graph (#24)
Fix DateTimeLine time data loss (#193)
Fix no data for graphs with only zeroes (#148)
Support value formatter for pie graphs (#218) (thanks never-eat-yellow-snow)
Add new Box plot modes and outliers and set extremes as default (#226 #121 #149) (thanks djezar)
Add secondary_range option to set range for secondary values. (#203)
Maps are now plugins, they are removed from pygal core and moved to packages (pygal_maps_world, pygal_maps_fr, pygal_maps_ch, ...) (#225)
Dot now supports negative values
Fix dot with log scale (#201)
V 1.7.0
Remove DateY and replace it by real XY datetime, date, time and timedelta support. (#188)
Introduce new XY configuration options: `xrange`, `x_value_formatter`.
Add show_x_labels option to remove them and the x axis.
Set print_values to False by default.
Fix secondary serie text values when None in data. (#192)
V 1.6.2
Add margin_top, margin_right, margin_bottom, margin_left options which defaults to margin. (thanks djt)
Update django mime parameter from mimetype to content_type. (thanks kswiat)
Allow a color and a style parameter to value metadata.
V 1.6.1
Fix Decimal incompatibility
V 1.6.0
Adds config option missing_value_fill_truncation. (thanks sirlark)
Avoid HTTP 301 Moved Permanently (thanks jean)
Add a Django response method (thanks inlanger)
Fix setup.py (#170)
Fix format error on list like in table
Add legend_at_bottom_columns option to specify number of columns in legend when at bottom. (#157)
Fix secondary interpolation (#165)
Adds an extra class (axis) to horizontal guides if the label is "0" (#147) (thanks sirlark)
Add line stroke customization parameters to style.py (#154) (thanks blakev)
V 1.5.1
Add `stack_from_top` option to reverse stack graph data order
Minor fix for empty logarithmic chart
Reorders axes in SVG output. Fix #145 (thanks sirlark)
V 1.5.0
Add per serie configuration
Add half pie (thanks philt2001)
Make lxml an optionnal dependency (huge speed boost in pypy)
Add render_table (WIP)
Support colors in rgb / rgba for parametric styles
V 1.4.6
Add support for \n separated multiline titles (thanks sirlark)
New show_only_major_dots option (thanks Le-Stagiaire)
Remove 16 colors limitation
Fix 0 in range (thanks elpaso)
V 1.4.5
Fix y_labels map iterator exhaustion in python 3
V 1.4.4
Fix division by zero in spark text (thanks laserpony)
Fix config metaclass problem in python 3
Fix --version in pygal_gen
V 1.4.3
Allow arbitrary number of x-labels on line plot (thanks nsmgr8)
V 1.4.2
Fix broken tests
V 1.4.1
Fix value formatting in maps
V 1.4.0
Finally a changelog !
Hopefully fix weird major scale algorithm
Add options to customize major labels (y_labels_major, y_labels_major_every, y_labels_major_count)
Css can now be inline with the "inline:" prefix
Visited links bug fixed
Add french maps by department and region (This will be externalized in an extension later)
V 1.3.x
Whisker Box Plot
Python 3 fix
DateY X axis formatting (x_label_format)

1
CHANGELOG
Unescape View File

@ -0,0 +1 @@
docs/changelog.rst

9
docs/api.rst
Unescape View File

@ -0,0 +1,9 @@
===
API
===
.. toctree::
:maxdepth: 2
api/modules

10
docs/api/pygal.maps.rst
Unescape View File

@ -0,0 +1,10 @@
pygal.maps package
==================
Module contents
---------------
.. automodule:: pygal.maps
:members:
:undoc-members:
:show-inheritance:

107
docs/changelog.rst
Unescape View File

@ -0,0 +1,107 @@
=========
Changelog
=========
2.0.0 UNRELEASED
================
* Rework the ghost mechanism to come back to a more object oriented behavior, storing all state in a state object which is created on every render. (#161)
* Refactor maps
* Add world continents
* Add swiss cantons map (thanks sergedroz)
* Add inverse_y_axis options to reverse graph (#24)
* Fix DateTimeLine time data loss (#193)
* Fix no data for graphs with only zeroes (#148)
* Support value formatter for pie graphs (#218) (thanks never-eat-yellow-snow)
* Add new Box plot modes and outliers and set extremes as default (#226 #121 #149) (thanks djezar)
* Add secondary_range option to set range for secondary values. (#203)
* Maps are now plugins, they are removed from pygal core and moved to packages (pygal_maps_world, pygal_maps_fr, pygal_maps_ch, ...) (#225)
* Dot now supports negative values
* Fix dot with log scale (#201)
1.7.0
=====
* Remove DateY and replace it by real XY datetime, date, time and timedelta support. (#188)
* Introduce new XY configuration options: `xrange`, `x_value_formatter`.
* Add show_x_labels option to remove them and the x axis.
* Set print_values to False by default.
* Fix secondary serie text values when None in data. (#192)
1.6.2
=====
* Add margin_top, margin_right, margin_bottom, margin_left options which defaults to margin. (thanks djt)
* Update django mime parameter from mimetype to content_type. (thanks kswiat)
* Allow a color and a style parameter to value metadata.
1.6.1
=====
* Fix Decimal incompatibility
1.6.0
=====
* Adds config option missing_value_fill_truncation. (thanks sirlark)
* Avoid HTTP 301 Moved Permanently (thanks jean)
* Add a Django response method (thanks inlanger)
* Fix setup.py (#170)
* Fix format error on list like in table
* Add legend_at_bottom_columns option to specify number of columns in legend when at bottom. (#157)
* Fix secondary interpolation (#165)
* Adds an extra class (axis) to horizontal guides if the label is "0" (#147) (thanks sirlark)
* Add line stroke customization parameters to style.py (#154) (thanks blakev)
1.5.1
=====
* Add `stack_from_top` option to reverse stack graph data order
* Minor fix for empty logarithmic chart
* Reorders axes in SVG output. Fix #145 (thanks sirlark)
1.5.0
=====
* Add per serie configuration
* Add half pie (thanks philt2001)
* Make lxml an optionnal dependency (huge speed boost in pypy)
* Add render_table (WIP)
* Support colors in rgb / rgba for parametric styles
1.4.6
=====
* Add support for \n separated multiline titles (thanks sirlark)
* New show_only_major_dots option (thanks Le-Stagiaire)
* Remove 16 colors limitation
* Fix 0 in range (thanks elpaso)
1.4.5
=====
* Fix y_labels map iterator exhaustion in python 3
1.4.4
=====
* Fix division by zero in spark text (thanks laserpony)
* Fix config metaclass problem in python 3
* Fix --version in pygal_gen
1.4.3
=====
* Allow arbitrary number of x-labels on line plot (thanks nsmgr8)
1.4.2
=====
* Fix broken tests
1.4.1
=====
* Fix value formatting in maps
1.4.0
=====
* Finally a changelog !
* Hopefully fix weird major scale algorithm
* Add options to customize major labels (y_labels_major, y_labels_major_every, y_labels_major_count)
* Css can now be inline with the "inline:" prefix
* Visited links bug fixed
* Add french maps by department and region (This will be externalized in an extension later)
1.3.x
=====
* Whisker Box Plot
* Python 3 fix
* DateY X axis formatting (x_label_format)

32
docs/contributing.rst
Unescape View File

@ -0,0 +1,32 @@
============
Contributing
============
Github
======
Submit your bug reports and feature requests to the `github bug tracker <http://github.com/Kozea/pygal/issues>`_.
Testing
=======
Before submiting a pull request, please check that all tests still pass.
To do this install ``py.test`` and them run ``py.test`` in the root of your pygal clone:
.. code-block:: bash
[dev@dev pygal/]$ py.test
Even better if you have several python versions installed you can run ``tox``.
Continuous Integration
======================
The current build status can be seen at our `ymci <https://ymci.kozea.fr/project/view/12>`_

13
docs/documentation/first_steps.rst
Unescape View File

@ -1,7 +1,9 @@
First steps First steps
=========== ===========
First you need to download the pygal package, see the `download page <download.html>`_. .. caution::
First you need to install pygal, see `installing <.//installing.html>`_.
When it's done, you are ready to make your first chart: When it's done, you are ready to make your first chart:
@ -12,10 +14,11 @@ When it's done, you are ready to make your first chart:
bar_chart.add('Fibonacci', [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]) # Add some values bar_chart.add('Fibonacci', [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]) # Add some values
bar_chart.render_to_file('bar_chart.svg') # Save the svg to a file bar_chart.render_to_file('bar_chart.svg') # Save the svg to a file
Now you have a svg file called `bar_chart.svg` in your current directory. Now you should have a svg file called ``bar_chart.svg`` in your current directory.
You can open it with various programs such as your web browser, inkscape or any svg compatible viewer. You can open it with various programs such as your web browser, inkscape or any svg compatible viewer.
The resulting chart will be tho following: The resulting chart will be tho following:
.. pygal-code:: .. pygal-code::
@ -23,6 +26,12 @@ The resulting chart will be tho following:
bar_chart = pygal.Bar() bar_chart = pygal.Bar()
bar_chart.add('Fibonacci', [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]) bar_chart.add('Fibonacci', [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55])
.. caution::
pygal relies on svg css styling. This is sadly not fully supported by gnome `librsvg <https://wiki.gnome.org/action/show/Projects/LibRsvg>`_ and therefore can lead to black svg being displayed. This is not a bug in pygal. `See this bugzilla search <https://bugzilla.gnome.org/buglist.cgi?bug_status=__open__&content=css%20style&no_redirect=1&order=Importance&product=librsvg&query_format=specific>`_
To make a multiple series graph just add another one: To make a multiple series graph just add another one:
.. pygal-code:: .. pygal-code::

4
docs/documentation/index.rst
Unescape View File

@ -1,5 +1,5 @@
User documentation Documentation
================== =============
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

20
docs/documentation/sparks.rst
Unescape View File

@ -14,29 +14,17 @@ Basic
chart.render_sparkline() 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 Options
------- -------
It's the same for other options: Sparklines support the same options as normal charts but for those that are overriden by sparkline settings, pass them to the ``render_sparkline`` method:
.. pygal-code:: sparkline .. pygal-code:: sparkline
chart = pygal.Line() from pygal.style import RTDStyle
chart = pygal.Line(style=RTDStyle, interpolate='cubic')
chart.add('', [1, 3, 5, 16, 13, 3, 7]) chart.add('', [1, 3, 5, 16, 13, 3, 7])
chart.render_sparkline(interpolate='cubic') chart.render_sparkline()
.. pygal-code:: sparkline .. pygal-code:: sparkline

1
docs/ext/pygal_sphinx_directives.py
Unescape View File

@ -110,6 +110,5 @@ class PygalWithCode(PygalDirective):
def setup(app): def setup(app):
app.add_directive('pygal', PygalDirective) app.add_directive('pygal', PygalDirective)
app.add_directive('pygal-code', PygalWithCode) app.add_directive('pygal-code', PygalWithCode)
app.add_directive('pygal-sparkline', PygalWithCode)
return {'version': '1.0.1'} return {'version': '1.0.1'}

108
docs/index.rst
Unescape View File

@ -2,123 +2,59 @@
Pygal Pygal
===== =====
Presentation Sexy python charting
============ ====================
pygal is a SVG charting library written in python.
.. pygal:: 300 200 .. pygal:: 300 200
chart = pygal.HorizontalBar(y_label_rotation=-25) chart = pygal.HorizontalBar(y_label_rotation=-25)
chart.x_labels = 'one', 'two', 'three', 'four', 'five' chart.x_labels = 'one', 'two', 'three', 'four', 'five'
chart.add('red', [1, 2, 3, 1, 2]) chart.add('alpha', [1, 2, 3, 1, 2])
chart.add('green', [4, 3, 0, 1, 2]) chart.add('beta', [4, 3, 0, 1, 2])
.. pygal:: 300 200 .. pygal:: 300 200
chart = pygal.Line(x_label_rotation=25, fill=True, style=pygal.style.NeonStyle, interpolate='cubic') chart = pygal.Line(x_label_rotation=25, fill=True, style=pygal.style.NeonStyle, interpolate='cubic')
chart.x_labels = 'one', 'two', 'three', 'four', 'five' chart.x_labels = 'one', 'two', 'three', 'four', 'five'
chart.add('red', [1, 2, 3, 1, 2]) chart.add('alpha', [1, 2, 3, 1, 2])
chart.add('green', [4, 3, 0, 1, 2]) chart.add('beta', [4, 3, 0, 1, 2])
.. pygal:: 300 200 .. pygal:: 300 200
chart = pygal.Pie() chart = pygal.Pie()
chart.x_labels = 'one', 'two', 'three', 'four', 'five' chart.x_labels = 'one', 'two', 'three', 'four', 'five'
chart.add('red', [1, 2, 3, 1, 2]) chart.add('alpha', [1, 2, 3, 1, 2])
chart.add('green', [4, 3, 0, 1, 2]) chart.add('beta', [4, 3, 0, 1, 2])
.. pygal:: 300 200 .. pygal:: 300 200
chart = pygal.Radar(fill=True, style=pygal.style.NeonStyle) chart = pygal.Radar(fill=True, style=pygal.style.NeonStyle)
chart.x_labels = 'one', 'two', 'three', 'four', 'five' chart.x_labels = 'one', 'two', 'three', 'four', 'five'
chart.add('red', [1, 2, 3, 1, 2]) chart.add('alpha', [1, 2, 3, 1, 2])
chart.add('green', [4, 3, 0, 1, 2]) chart.add('beta', [4, 3, 0, 1, 2])
It features various graph types:
- `Bar charts <documentation/chart_types.html#bar-charts-histograms>`_ Simple python charting
======================
- `Line charts <documentation/chart_types.html#line-charts>`_ .. pygal-code::
- `XY charts <documentation/chart_types.html#xy-charts>`_ chart = pygal.Bar()
chart.add('First', [1, 3, 3, 7])
- `Pie charts <documentation/chart_types.html#pies>`_
- `Radar charts <documentation/chart_types.html#radar-charts>`_ Index
=====
- `Box plot <documentation/chart_types.html#box-plot>`_
- `Dot charts <documentation/chart_types.html#dot-charts>`_
- `Pyramid charts <documentation/chart_types.html#pyramid-charts>`_
- `Funnel charts <documentation/chart_types.html#funnel-charts>`_
- `Gauge charts <documentation/chart_types.html#gauge-charts>`_
- `Worldmap charts <documentation/chart_types.html#worldmap-charts>`_
- `Country charts <documentation/chart_types.html#country-charts>`_
Python/Css styling with some pre-defined themes. See `styling <styles.html>`_.
And a lot of options to `customize the charts. <basic_customizations.html>`_
Get it !
========
- Get the package on `pypi <http://pypi.python.org/pypi/pygal/>`_
- Fork me on `github <http://github.com/Kozea/pygal>`_
More information in the `download page <download.html>`_
Get started
===========
Start `here <first_steps.html>`_ to make your first steps.
Technical Description
=====================
As of now pygal is known to work for python 2.6, 2.7 and 3.2, 3.3, 3.4.
Needed dependencies
-------------------
pygal uses `lxml <http://lxml.de/>`_ to generate the svg, this is the only needed dependency.
Optional dependencies
---------------------
PNG output requires `CairoSVG <http://cairosvg.org/>`_, `tinycss <http://packages.python.org/tinycss/>`_ and `cssselect <http://packages.python.org/cssselect/>`_.
Install those with ``pip install CairoSVG tinycss cssselect``.
Unit testing needs `py.test <http://pytest.org/latest/>`_ or `nosetests <http://readthedocs/org/docs/nose/en/latest/>`_.
Visual testing is based on `flask <http://flask.pocoo.org/>`_.
Read more
=========
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 1
documentation/index documentation/index
download installing
support contributing
api/modules changelog
api
Indices and tables
==================
* :ref:`genindex` * :ref:`genindex`
* :ref:`modindex` * :ref:`modindex`

15
docs/download.rst → docs/installing.rst
Unescape View File

@ -1,15 +1,16 @@
========== ==========
Download Installing
========== ==========
PyPI PyPI
==== ====
pygal is `available on PyPI <http://pypi.python.org/pypi/pygal/>`_. To pygal is `available on PyPI <http://pypi.python.org/pypi/pygal/>`_.
install, just type as superuser:: To install, just type as superuser::
pip install pygal pip install pygal
Git Repository Git Repository
============== ==============
@ -20,12 +21,16 @@ If you want the development version of pygal, take a look at the
You can also download `the development snapshot from github <http://github.com/Kozea/pygal/tarball/master>`_. You can also download `the development snapshot from github <http://github.com/Kozea/pygal/tarball/master>`_.
Linux Distribution Packages Linux Distribution Packages
=========================== ===========================
Pygal has been packaged for: Pygal has been packaged for:
- `Fedora <https://admin.fedoraproject.org/pkgdb/acls/name/python-pygal>`_ by ralph - `Fedora <https://admin.fedoraproject.org/pkgdb/acls/name/python-pygal>`_
- `Gentoo <http://packages.gentoo.org/package/dev-python/pygal>`_ by Ben de Groot - `Gentoo <http://packages.gentoo.org/package/dev-python/pygal>`_
- `Ubuntu <https://launchpad.net/ubuntu/+source/python-pygal`_
- `Debian <https://packages.debian.org/unstable/python-pygal>`_
- `Arch Linux <https://aur.archlinux.org/packages/python-pygal/>`_
If you are interested in creating packages for Linux distributions, `contact us <support.html>`_. If you are interested in creating packages for Linux distributions, `contact us <support.html>`_.

11
docs/support.rst
Unescape View File

@ -1,11 +0,0 @@
=========
Support
=========
Github
======
Submit your bug reports and your feature requests to the `github bug tracker <http://github.com/Kozea/pygal/issues>`_.
Never hesitate to fork the project on github.
Pull requests are always welcomed.

22
pygal/maps/__init__.py
Unescape View File

@ -0,0 +1,22 @@
# -*- coding: utf-8 -*-
# This file is part of pygal
#
# A python svg graph plotting library
# Copyright © 2012-2015 Kozea
#
# This library is free software: you can redistribute it and/or modify it under
# the terms of the GNU Lesser General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your option) any
# later version.
#
# This library is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
# details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pygal. If not, see <http://www.gnu.org/licenses/>.
"""
Maps extensions namespace module
"""
Write Preview
Loading…
Cancel
Save