Skip to content

Commit

Permalink
Merge cbf9d3c into 3e52ecb
Browse files Browse the repository at this point in the history
  • Loading branch information
Jonathan Rocher committed Nov 6, 2014
2 parents 3e52ecb + cbf9d3c commit bf295c2
Showing 1 changed file with 125 additions and 62 deletions.
187 changes: 125 additions & 62 deletions docs/source/quickstart.rst
View file
Expand Up @@ -19,20 +19,22 @@ post questions, consult archives, and share tips.
Installation
============

There are several ways to get Chaco. The easiest way is through the `Enthought
Python Distribution (EPD) <http://www.enthought.com/epd>`_, which is available
for several platforms and also provides many other useful packages. Chaco may
also be available through a package manager on your platform, such as apt on
Ubuntu or `MacPorts <http://www.macports.org/>`_ on OS X. You can also build
Chaco yourself, but because of the number of packages required, we highly
recommend you install EPD.
There are several ways to get Chaco. The easiest way is through
`Enthought Canopy <https://www.enthought.com/products/canopy/>`_ (formerly
EPD), which is available for Windows, Linux and Mac OSX and also provides many
other useful packages.
Chaco may also be available through a package manager on your platform, such as
apt on Ubuntu, yum on Redhat or `MacPorts <http://www.macports.org/>`_ on OS X.
You can also build Chaco yourself from its
`source code <https://github.com/enthought/chaco>`_, but because of the number
of dependencies, the easiest way is by far to install Enthought Canopy.

.. _dependencies:

Dependencies
------------

* `Python <https://www.python.org>`_ 2.5 or later
* `Python <https://www.python.org>`_ 2.5-2.7 (Python 3 support on the way)

* `Traits <https://github.com/enthought/traits>`_, an event notification
framework
Expand All @@ -42,65 +44,78 @@ Dependencies

* `Enable <https://github.com/enthought/enable/>`_, a framework for writing
interactive visual components, and for abstracting away GUI-toolkit-specific
details of mouse and keyboard handling
details of mouse and keyboard handling. This currently still depends on the
Python Image Library (PIL).

* `NumPy <http://numpy.scipy.org/>`_, for dealing efficiently with large
datasets

* Either `wxPython <http://www.wxpython.org/>`_ or `PyQt
<http://www.riverbankcomputing.co.uk/software/pyqt/intro>`_ to display
interactive plots. As an alternative to PyQt, Chaco is being tested more and
more with the `PySide <http://www.pyside.org/>`_ toolkit (LGPL license).
* Either `wxPython <http://www.wxpython.org/>`_,
`PyQt <http://www.riverbankcomputing.co.uk/software/pyqt/intro>`_ (GPL or
Commercial license) or `PySide <http://www.pyside.org/>`_ (LGPL license) to
display interactive plots.

.. .. note
.. ::
.. In addition to wxPython or PyQt a cross-platform OpenGL backend (using
.. Pyglet) is in the works, and it will not require WX or Qt.
Installing Chaco with EPD
-------------------------
Installing Chaco with Enthought Canpopy
---------------------------------------

Chaco, the rest of the `Enthought Tool Suite <http://code.enthought.com/>`_,
and a lot more are bundled with EPD. Getting EPD allows you to install Chaco
and all its dependencies at once; however, these packages will be linked to a
new instance of Python. The EPD Free distribution is free for all users and
contains all that you need to use Chaco.
and a lot more are bundled with Enthought Canopy (formerly EPD). Getting
Enthought Canopy give you a one-click install of Chaco and all its
dependencies; however, these packages will be linked to a new instance of
Python. The Enthought Canopy Express is free for all users and contains all
that you need to use Chaco.

To get EPD, go to the `EPD download page
<http://www.enthought.com/products/getepd.php>`_ and get the appropriate
version for your platform. After running the installer, you will have a
working version of Chaco and several examples.
To get Enthought Canopy, go to the `Enthought Canopy download page
<https://store.enthought.com/>`_, select the desired level (Express, Full,
TriplePlay) and get the appropriate version for your platform. After running
the installer, you will have a working version of Chaco and several examples.

Building Chaco
--------------
Installing Chaco into an existing Python distribution
------------------------------------------------------

Building Chaco on your machine requires you to build Chaco and each of its
dependencies, but it has the advantage of installing Chaco on top of the Python
instance you already have installed. The build process may be challenging and
will require you to have SWIG, Cython and several development libraries
installed.
will require you to have C compiler, SWIG, Cython and several development
libraries installed.

To do this, you can either
To do this, you can either:

1. Install Chaco and its :ref:`dependencies` from `PyPI
<http://pypi.python.org/pypi>`_ using `easy_install
<http://pypi.python.org/pypi>`_ using
`pip <http://www.pip-installer.org/en/latest/>`_ or using `easy_install
<http://packages.python.org/distribute/easy_install.html>`_ (part of
setuptools) or using `pip <http://www.pip-installer.org/en/latest/>`_. For
example
setuptools). For example

:command:`easy_install chaco`
:command:`pip install chaco`

or

:command:`pip install chaco`
:command:`easy_install chaco`

2. Or, download the source from the `Chaco GitHub repository
<https://github.com/enthought/chaco>`_ or alternatively as a part of `ETS
<http://code.enthought.com/source/>`_.

.. Please refer to the :ref:`installation` section for more detailed
.. instructions.
.. TODO This 'installation' section does not currently exist
.. note::
If you have already install Chaco and just want to update to the newest
version, use

:command:`pip install --upgrade chaco`

.. note::
Because Chaco depends on Enable which depends on PIL, certain platforms
cannot install PIL from PyPI without these options:

:command:`pip install --allow-external PIL --allow-unverified PIL chaco`


2. Or, download the source from the `Chaco GitHub repository
<https://github.com/enthought/chaco>`_ or alternatively as a part of the
full `Enthought Tool Suite <http://code.enthought.com/source/>`_.


Built-in Examples
Expand All @@ -114,11 +129,29 @@ you may or may not have the examples already.
Location
--------

1. If you installed Chaco as part of EPD, the location of the examples depends
on your platform:
1. If you installed Chaco as part of Enthought Canopy, the location of the
examples depends on your platform:

* On Windows, they are in the :file:`Examples\\` subdirectory of your
installation location. This is typically
:file:`C:\\Users\\<username>\\AppData\\Local\\Enthought\\Canopy\\User\\Examples\\Chaco-<version>`. These examples can also
be browsed from the start menu, by clicking:
:menuselection:`Start --> Applications --> Enthought Canopy --> Example Browser`.

* On Windows, they are in the Examples\\ subdirectory of your installation
location. This is typically
* On Linux, they are in the
:file:`Enthought/Canopy_XXbit/User/Examples/chaco-<version>` subdirectory
of your installation location.

* On Mac OS X, they are in the
:file:`~/Library/Enthought/Canopy_XXbit/User/Examples/chaco-<version>`
directory.


2. If you installed Chaco as part of EPD, the location of the examples also
depends on your platform:

* On Windows, they are in the :file:`Examples\\` subdirectory of your
installation location. This is typically
:file:`C:\\Python27\\Examples\\Chaco-<version>`. On MS Windows these
examples can be browsed from the start menu, by clicking
:menuselection:`Start --> Applications --> Enthought --> Examples`.
Expand All @@ -129,23 +162,21 @@ Location
* On Mac OS X, they are in the
:file:`/Applications/Enthought/Examples/chaco-<version>` directory.

2. If you downloaded and installed Chaco from source (from GitHub or via the
3. If you downloaded and installed Chaco from source (from GitHub or via the
PyPI tar.gz file), the examples are located in the :file:`examples/`
subdirectory inside the root of the Chaco source tree, next to :file:`docs/`
and the :file:`enthought/` directories.
and the :file:`chaco/` directories.

3. If you don't know how Chaco was installed, you can download the latest
4. If you don't know how Chaco was installed, you can download the latest
versions of examples individually from github:

https://github.com/enthought/chaco/tree/master/examples

For ETS 3.0 or Chaco 3.0, you can check out the examples with Subversion:

:command:`svn co https://svn.enthought.com/svn/enthought/Chaco/tags/3.0.0/examples`

For ETS 2.8 or Chaco 2.0.x:

:command:`svn co https://svn.enthought.com/svn/enthought/Chaco/tags/enthought.chaco2_2.0.5/examples`
.. Deprecated: svn.enthought not accessible anymore
.. For ETS 3.0 or Chaco 3.0, you can check out the examples with Subversion:
.. :command:`svn co https://svn.enthought.com/svn/enthought/Chaco/tags/3.0.0/examples`
.. For ETS 2.8 or Chaco 2.0.x:
.. :command:`svn co https://svn.enthought.com/svn/enthought/Chaco/tags/enthought.chaco2_2.0.5/examples`
Chaco examples can be found in the :file:`examples/demo/` and
:file:`examples/tutorials/` directories. Some are classified by themes and
Expand Down Expand Up @@ -239,12 +270,13 @@ This shows two overlapping line plots.

You can interact with this plot just as in the previous section.

Now exit the plot, and start IPython with the ``--gui=wx`` option [#guiqt]_:
Now close the plot, and start IPython with the ``--gui=qt`` [#guiqt]_ or
``--gui=wx`` option:

:command:`ipython --gui=wx`
:command:`ipython --gui=qt`

This tells IPython to start a wxPython mainloop in a background thread. Now
run the previous example again::
This tells IPython to start a Qt or WX mainloop in a background thread. Now run
the previous example again::

In [1]: run lines.py

Expand Down Expand Up @@ -280,8 +312,13 @@ information on all you can do with Chaco from within IPython.
Chaco plot embedded in a Traits application
===========================================

Let's create, from scratch, the simplest possible Chaco plot (embedded inside a
`Traits`_ application).
The previous section showed how Chaco can be used interactively similarly to
`Matlab` or Matplotlib's `pyplot` package.

Now, let's create, from scratch, the simplest possible Chaco plot which
embedded inside a `Traits`_ application. This will require more work but will
represent the basis for a potential large-scale, custom and powerful rich
client application. This is really what Chaco has been written for.

First, some imports to bring in necessary components::

Expand Down Expand Up @@ -346,9 +383,8 @@ relatively simple basis on top of which we can build full-featured applications
with custom UIs and custom tools. For example, the Traits object allows you to
create controls for your plot at a very high level, add these controls to the
UI with very little work, and add listeners to update the plot when the data
changes. Chaco also allows you to create tools to interact with the plot and
overlays that make these tools intuitive and visually appealing.

changes. Chaco also allows you to create custom tools to interact with the
plot and overlays that make these tools intuitive and visually appealing.

.. rubric:: Footnotes

Expand All @@ -358,8 +394,35 @@ overlays that make these tools intuitive and visually appealing.
<http://ipython.org/ipython-doc/dev/interactive/reference.html?highlight=qt_api#pyqt-and-pyside>`_
Where to learn more?
=====================

To learn more about the power of Chaco and build powerful rich client
applications with custom visualizations, consider going over the
:ref:`tutorials` section or learning from the :ref:`user_guide`.


License
=======

As part of the `Enthought Tool Suite <http://code.enthought.com/>`_, Chaco is
free and open source under the BSD license.


Reporting bugs and contributing
===============================

Since Chaco is open source and hosted on
`Github <https://github.com/enthought/chaco>`_, the development version can
always to checked out from Github, forked, and modified at will.
When a bug is found, please submit an issue in the
`issue page <https://github.com/enthought/chaco/issues>`_
If you would like to share a bug fix or a new feature, simply submit a Pull
Request from your fork.
Don't forget to specify very clearly what code to run to reproduce the issue,
what the logic of the fix is and to add one or more unit test to ensure future
stability. The Pull Request description can and often needs to contain
screenshots of the issue or the fix. Finally, it is always a good idea to
consider discuss the feature/bug and the
fix in the `enthought-dev
<https://mail.enthought.com/mailman/listinfo/enthought-dev>`_ mailing list.

0 comments on commit bf295c2

Please sign in to comment.