Browse Source

Start updating docs. + Re organize again + Include changelog

pull/242/head
Florian Mounier 10 years ago
parent
commit
633bcda573
  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

@ -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

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

9
docs/api.rst

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

10
docs/api/pygal.maps.rst

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

107
docs/changelog.rst

@ -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

@ -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

@ -1,7 +1,9 @@
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:
@ -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.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.
The resulting chart will be tho following:
.. pygal-code::
@ -23,6 +26,12 @@ The resulting chart will be tho following:
bar_chart = pygal.Bar()
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:
.. pygal-code::

4
docs/documentation/index.rst

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

20
docs/documentation/sparks.rst

@ -14,29 +14,17 @@ Basic
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:
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
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.render_sparkline(interpolate='cubic')
chart.render_sparkline()
.. pygal-code:: sparkline

1
docs/ext/pygal_sphinx_directives.py

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

108
docs/index.rst

@ -2,123 +2,59 @@
Pygal
=====
Presentation
============
Sexy python charting
====================
pygal is a SVG charting library written in python.
.. pygal:: 300 200
chart = pygal.HorizontalBar(y_label_rotation=-25)
chart.x_labels = 'one', 'two', 'three', 'four', 'five'
chart.add('red', [1, 2, 3, 1, 2])
chart.add('green', [4, 3, 0, 1, 2])
chart.add('alpha', [1, 2, 3, 1, 2])
chart.add('beta', [4, 3, 0, 1, 2])
.. pygal:: 300 200
chart = pygal.Line(x_label_rotation=25, fill=True, style=pygal.style.NeonStyle, interpolate='cubic')
chart.x_labels = 'one', 'two', 'three', 'four', 'five'
chart.add('red', [1, 2, 3, 1, 2])
chart.add('green', [4, 3, 0, 1, 2])
chart.add('alpha', [1, 2, 3, 1, 2])
chart.add('beta', [4, 3, 0, 1, 2])
.. pygal:: 300 200
chart = pygal.Pie()
chart.x_labels = 'one', 'two', 'three', 'four', 'five'
chart.add('red', [1, 2, 3, 1, 2])
chart.add('green', [4, 3, 0, 1, 2])
chart.add('alpha', [1, 2, 3, 1, 2])
chart.add('beta', [4, 3, 0, 1, 2])
.. pygal:: 300 200
chart = pygal.Radar(fill=True, style=pygal.style.NeonStyle)
chart.x_labels = 'one', 'two', 'three', 'four', 'five'
chart.add('red', [1, 2, 3, 1, 2])
chart.add('green', [4, 3, 0, 1, 2])
chart.add('alpha', [1, 2, 3, 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>`_
- `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
=========
Index
=====
.. toctree::
:maxdepth: 2
:maxdepth: 1
documentation/index
download
support
api/modules
Indices and tables
==================
installing
contributing
changelog
api
* :ref:`genindex`
* :ref:`modindex`

15
docs/download.rst → docs/installing.rst

@ -1,15 +1,16 @@
==========
Download
Installing
==========
PyPI
====
pygal is `available on PyPI <http://pypi.python.org/pypi/pygal/>`_. To
install, just type as superuser::
pygal is `available on PyPI <http://pypi.python.org/pypi/pygal/>`_.
To install, just type as superuser::
pip install pygal
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>`_.
Linux Distribution Packages
===========================
Pygal has been packaged for:
- `Fedora <https://admin.fedoraproject.org/pkgdb/acls/name/python-pygal>`_ by ralph
- `Gentoo <http://packages.gentoo.org/package/dev-python/pygal>`_ by Ben de Groot
- `Fedora <https://admin.fedoraproject.org/pkgdb/acls/name/python-pygal>`_
- `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>`_.

11
docs/support.rst

@ -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

@ -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
"""
Loading…
Cancel
Save