From 41080b1d5c374946094e8063dbb03a56656b8605 Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Tue, 15 May 2018 01:38:34 -0700
Subject: [PATCH] Update INSTALL.rst.
- Dedent the overindented bullet lists.
- Add a link for FreeType.
- Suggest `python -mpytest` instead of `pytest` to run the tests for the
same reason as `python -mpip` is suggested (avoids invoking an
out-of-venv pytest).
- Clarify the situation regarding pycairo/cairocffi (the former works
for everything and is a requirement for gtk3 (unless you're using pgi,
but in that case you're mostly on your own)).
---
INSTALL.rst | 88 +++++++++++++++++++++++++++--------------------------
1 file changed, 45 insertions(+), 43 deletions(-)
diff --git a/INSTALL.rst b/INSTALL.rst
index bb2402ede7da..bda6843ae3d0 100644
--- a/INSTALL.rst
+++ b/INSTALL.rst
@@ -38,23 +38,25 @@ macOS
To use the native OSX backend you will need :ref:`a framework build
<osxframework-faq>` build of Python.
-Test Data
+Test data
---------
The wheels (:file:`*.whl`) on the `PyPI download page
<https://pypi.python.org/pypi/matplotlib/>`_ do not contain test data
or example code.
+
If you want to try the many demos that come in the Matplotlib source
distribution, download the :file:`*.tar.gz` file and look in the
:file:`examples` subdirectory.
+
To run the test suite:
- * extract the :file:`lib/matplotlib/tests` or
- :file:`lib/mpl_toolkits/tests` directories from the source distribution;
- * install test dependencies: `pytest <https://pypi.python.org/pypi/pytest>`_,
- Pillow, MiKTeX, GhostScript, ffmpeg, avconv, ImageMagick, and `Inkscape
- <https://inkscape.org/>`_;
- * run ``pytest path\to\tests\directory``.
+* extract the :file:`lib/matplotlib/tests` or :file:`lib/mpl_toolkits/tests`
+ directories from the source distribution;
+* install test dependencies: `pytest <https://pypi.python.org/pypi/pytest>`_,
+ Pillow, MiKTeX, GhostScript, ffmpeg, avconv, ImageMagick, and `Inkscape
+ <https://inkscape.org/>`_;
+* run ``python -mpytest``.
Third-party distributions of Matplotlib
=======================================
@@ -68,12 +70,12 @@ Scientific Python Distributions
<https://www.enthought.com/products/canopy/>`_ and `ActiveState
<https://www.activestate.com/activepython/downloads>`_ are excellent
choices that "just work" out of the box for Windows, macOS and common
-Linux platforms. `WinPython <https://winpython.github.io/>`__ is an
-option for windows users. All of these distributions include
+Linux platforms. `WinPython <https://winpython.github.io/>`_ is an
+option for Windows users. All of these distributions include
Matplotlib and *lots* of other useful (data) science tools.
-Linux : using your package manager
-----------------------------------
+Linux: using your package manager
+---------------------------------
If you are on Linux, you might prefer to use your package manager. Matplotlib
is packaged for almost every major Linux distribution.
@@ -133,48 +135,48 @@ Dependencies
Matplotlib requires the following dependencies:
- * `Python <https://www.python.org/downloads/>`_ (>= 3.5)
- * `NumPy <http://www.numpy.org>`_ (>= |minimum_numpy_version|)
- * `setuptools <https://setuptools.readthedocs.io/en/latest/>`__
- * `dateutil <https://pypi.python.org/pypi/python-dateutil>`_ (>= 2.1)
- * `pyparsing <https://pyparsing.wikispaces.com/>`__
- * `libpng <http://www.libpng.org>`__ (>= 1.2)
- * `pytz <http://pytz.sourceforge.net/>`__
- * FreeType (>= 2.3)
- * `cycler <http://matplotlib.org/cycler/>`__ (>= 0.10.0)
- * `six <https://pypi.python.org/pypi/six>`_ (>= 1.10)
- * `kiwisolver <https://github.com/nucleic/kiwi>`__ (>= 1.0.0)
+* `Python <https://www.python.org/downloads/>`_ (>= 3.5)
+* `NumPy <http://www.numpy.org>`_ (>= |minimum_numpy_version|)
+* `setuptools <https://setuptools.readthedocs.io/en/latest/>`_
+* `dateutil <https://pypi.python.org/pypi/python-dateutil>`_ (>= 2.1)
+* `pyparsing <https://pyparsing.wikispaces.com/>`_
+* `libpng <http://www.libpng.org>`_ (>= 1.2)
+* `pytz <http://pytz.sourceforge.net/>`_
+* `FreeType <https://www.freetype.org/>`_ (>= 2.3)
+* `cycler <http://matplotlib.org/cycler/>`_ (>= 0.10.0)
+* `six <https://pypi.python.org/pypi/six>`_ (>= 1.10)
+* `kiwisolver <https://github.com/nucleic/kiwi>`_ (>= 1.0.0)
Optionally, you can also install a number of packages to enable better user
interface toolkits. See :ref:`what-is-a-backend` for more details on the
optional Matplotlib backends and the capabilities they provide.
- * :term:`tk` (>= 8.3, != 8.6.0 or 8.6.1): for the TkAgg backend;
- * `PyQt4 <https://pypi.python.org/pypi/PyQt4>`_ (>= 4.4) or
- `PySide <https://pypi.python.org/pypi/PySide>`_: for the Qt4Agg backend;
- * `PyQt5 <https://pypi.python.org/pypi/PyQt5>`_: for the Qt5Agg backend;
- * :term:`wxpython` (>= 2.9 or later): for the WX or WXAgg backend;
- * `cairocffi <https://cairocffi.readthedocs.io/en/latest/>`__ (>=
- v0.8): for cairo based backends;
- * `pycairo <https://pypi.python.org/pypi/pycairo>`_: for GTK3Cairo;
- * `Tornado <https://pypi.python.org/pypi/tornado>`_: for the WebAgg backend;
+* :term:`tk` (>= 8.3, != 8.6.0 or 8.6.1): for the TkAgg backend;
+* `PyQt4 <https://pypi.python.org/pypi/PyQt4>`_ (>= 4.4) or
+ `PySide <https://pypi.python.org/pypi/PySide>`_: for the Qt4Agg backend;
+* `PyQt5 <https://pypi.python.org/pypi/PyQt5>`_: for the Qt5Agg backend;
+* :term:`wxpython` (>= 4): for the WX or WXAgg backend;
+* `cairocffi <https://cairocffi.readthedocs.io/en/latest/>`_ (>=0.8) or
+ `pycairo <https://pypi.python.org/pypi/pycairo>`_: for the cairo-based
+ backends (the latter is required for GTK3Cairo);
+* `Tornado <https://pypi.python.org/pypi/tornado>`_: for the WebAgg backend;
For better support of animation output format and image file formats, LaTeX,
etc., you can install the following:
- * `ffmpeg <https://www.ffmpeg.org/>`_/`avconv
- <https://libav.org/avconv.html>`_: for saving movies;
- * `ImageMagick <https://www.imagemagick.org/script/index.php>`_: for saving
- animated gifs;
- * `Pillow <https://pillow.readthedocs.io/en/latest/>`_ (>=3.4): for a larger selection of
- image file formats: JPEG, BMP, and TIFF image files;
- * `LaTeX <https://miktex.org/>`_ and `GhostScript
- <https://ghostscript.com/download/>`_ (for rendering text with LaTeX).
+* `ffmpeg <https://www.ffmpeg.org/>`_/`avconv
+ <https://libav.org/avconv.html>`_: for saving movies;
+* `ImageMagick <https://www.imagemagick.org/script/index.php>`_: for saving
+ animated gifs;
+* `Pillow <https://pillow.readthedocs.io/en/latest/>`_ (>=3.4): for a larger
+ selection of image file formats: JPEG, BMP, and TIFF image files;
+* `LaTeX <https://miktex.org/>`_ and `GhostScript
+ <https://ghostscript.com/download/>`_ (for rendering text with LaTeX).
.. note::
Matplotlib depends on non-Python libraries. `pkg-config
- <https://www.freedesktop.org/wiki/Software/pkg-config/>`__ can be used
+ <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ can be used
to find required non-Python libraries and thus make the install go more
smoothly if the libraries and headers are not in the expected locations.
@@ -182,9 +184,9 @@ etc., you can install the following:
The following libraries are shipped with Matplotlib:
- - `Agg`: the Anti-Grain Geometry C++ rendering engine;
- - `qhull`: to compute Delaunay triangulation;
- - `ttconv`: a true type font utility.
+ - `Agg`: the Anti-Grain Geometry C++ rendering engine;
+ - `qhull`: to compute Delaunay triangulation;
+ - `ttconv`: a TrueType font utility.
.. _build_linux: