From 0acf41e3c56445b9cd75bb0a53866f31f4435e28 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Wed, 8 Mar 2017 11:41:26 -0800 Subject: [PATCH 01/13] DOC refactored installation instruction --- INSTALL | 99 +++++++++++++++++++++++++++++++++++++++++++++++++-- README.osx | 31 ---------------- README.rst | 18 ++++++---- README.win.md | 67 ---------------------------------- 4 files changed, 107 insertions(+), 108 deletions(-) delete mode 100644 README.osx delete mode 100644 README.win.md diff --git a/INSTALL b/INSTALL index e176a8bac16f..8f757db54e5d 100644 --- a/INSTALL +++ b/INSTALL @@ -3,9 +3,9 @@ .. Therefore, you must edit INSTALL, *not* doc/users/installing.rst! .. _pip: https://pypi.python.org/pypi/pip/ -********** +========== Installing -********** +========== There are many different ways to install matplotlib, and the best way depends on what operating system you are using, what you already have @@ -325,7 +325,32 @@ can get the libpng and freetype requirements (darwinports, fink, /usr/X11R6) and the different architectures (e.g., x86, ppc, universal) and the different OSX version (e.g., 10.4 and 10.5). We recommend that you build the way we do for the OSX release: get the source from the tarball or the -git repository and follow the instruction in :file:`README.osx`. +git repository and install the required dependencies through a third-party +package manager: two widely used package managers are homebrew, and MacPorts. +The following example illustrates how to install libpng and freetype using +brew: + +Example usage:: + + brew install libpng freetype pkg-config + +If you are using MacPorts, execute the following instead: + +Example usage:: + + port install libpng freetype pkgconfig + +To install matplotlib from source, execute: + +Example usage:: + + python setup.py install + + +Note that your environment is somewhat important. Some conda users have +found that, to run the tests, their PYTHONPATH must include +/path/to/anaconda/.../site-packages and their DYLD_FALLBACK_LIBRARY_PATH +must include /path/to/anaconda/lib. .. _build_windows: @@ -341,3 +366,71 @@ with the same compiler. Since there is no canonical Windows package manager, the methods for building freetype, zlib, and libpng from source code are documented as a build script at `matplotlib-winbuild `_. + + +There are a few possibilities to build matplotlib on Windows: + +* Wheels via `matplotlib-winbuild `_ +* Wheels by using conda packages +* Conda packages + +Wheel builds using conda packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is a wheel build, but we use conda packages to get all the requirements. The binary +requirements (png, freetype,...) are statically linked and therefore not needed during the wheel +install. + +The commands below assume that you can compile a native python lib for the python version of your +choice. See `this howto `_ +how to install and setup such environments. If in doubt: use python 3.5 as it mostly works +without fiddling with environment variables:: + + # create a new environment with the required packages + conda create -n "matplotlib_build" python=3.4 numpy python-dateutil pyparsing pytz tornado "cycler>=0.10" tk libpng zlib freetype + activate matplotlib_build + # if you want a qt backend, you also have to install pyqt (be aware that pyqt doesn't mix well if + # you have created the environment with conda-forge already activated...) + conda install pyqt + # this package is only available in the conda-forge channel + conda install -c conda-forge msinttypes + # for python 2.7 + conda install -c conda-forge backports.functools_lru_cache + + # copy the libs which have "wrong" names + set LIBRARY_LIB=%CONDA_DEFAULT_ENV%\Library\lib + mkdir lib || cmd /c "exit /b 0" + copy %LIBRARY_LIB%\zlibstatic.lib lib\z.lib + copy %LIBRARY_LIB%\libpng_static.lib lib\png.lib + + # Make the header files and the rest of the static libs available during the build + # CONDA_DEFAULT_ENV is a env variable which is set to the currently active environment path + set MPLBASEDIRLIST=%CONDA_DEFAULT_ENV%\Library\;. + + # build the wheel + python setup.py bdist_wheel + +The `build_alllocal.cmd` script in the root folder automates these steps if +you already created and activated the conda environment. + + +Conda packages +^^^^^^^^^^^^^^ + +This needs a `working installed C +compiler +`_ +for the version of python you are compiling the package for but you don't need +to setup the environment variables:: + + # only the first time... + conda install conda-build + + # the python version you want a package for... + set CONDA_PY=3.5 + + # builds the package, using a clean build environment + conda build ci\conda_recipe + + # install the new package + conda install --use-local matplotlib diff --git a/README.osx b/README.osx deleted file mode 100644 index 0b30c3d98101..000000000000 --- a/README.osx +++ /dev/null @@ -1,31 +0,0 @@ -Building mpl on OSX is sometimes a nightmare because of all the -different types of zlib, png and freetype that may be on your system. - -For developers who want to build matplotlib from source, the recommended and -supported way to build is to use a third-party package manager to install the -required dependencies, and then install matplotlib from source using the -setup.py script. Two widely used package managers are homebrew, and -MacPorts. The following example illustrates how to install libpng and freetype -using brew: - -Example usage:: - - brew install libpng freetype pkg-config - -If you are using MacPorts, execute the following instead: - -Example usage:: - - port install libpng freetype pkgconfig - -To install matplotlib from source, execute: - -Example usage:: - - python setup.py install - - -Note that your environment is somewhat important. Some conda users have -found that, to run the tests, their PYTHONPATH must include -/path/to/anaconda/.../site-packages and their DYLD_FALLBACK_LIBRARY_PATH -must include /path/to/anaconda/lib. diff --git a/README.rst b/README.rst index f60c4cca7b0e..4f8615cb8d3a 100644 --- a/README.rst +++ b/README.rst @@ -20,21 +20,25 @@ .. _Depsy: http://depsy.org/package/python/matplotlib ########## -matplotlib +Matplotlib ########## -matplotlib is a Python 2D plotting library which produces publication-quality -figures in a variety of hardcopy formats and interactive -environments across platforms. matplotlib can be used in Python -scripts, the Python and IPython shell (ala MATLAB or Mathematica), web -application servers, and various graphical user interface toolkits. +Matplotlib is a Python 2D plotting library which produces publication-quality +figures in a variety of hardcopy formats and interactive environments across +platforms. Matplotlib can be used in Python scripts, the Python and IPython +shell (ala MATLAB or Mathematica), web application servers, and various +graphical user interface toolkits. `Home page `_ Installation ============= -For installation instructions and requirements, see the INSTALL file or the `install `_ documentation. If you think you may want to contribute to matplotlib, check out the `guide to working with the source code `_. +For installation instructions and requirements, see the INSTALL file or the +`install `_ documentation. If you +think you may want to contribute to matplotlib, check out the `guide to +working with the source code +`_. Testing ======= diff --git a/README.win.md b/README.win.md deleted file mode 100644 index b6d481ed38e3..000000000000 --- a/README.win.md +++ /dev/null @@ -1,67 +0,0 @@ -# Building on Windows - -There are a few possibilities to build matplotlib on Windows: - -* Wheels via [matplotlib-winbuild](https://github.com/jbmohler/matplotlib-winbuild) -* Wheels by using conda packages -* Conda packages - -## Wheel builds using conda packages - -This is a wheel build, but we use conda packages to get all the requirements. The binary -requirements (png, freetype,...) are statically linked and therefore not needed during the wheel -install. - -The commands below assume that you can compile a native python lib for the python version of your -choice. See [this howto](http://blog.ionelmc.ro/2014/12/21/compiling-python-extensions-on-windows/) -how to install and setup such environments. If in doubt: use python 3.5 as it mostly works -without fiddling with environment variables. - -``` sh -# create a new environment with the required packages -conda create -n "matplotlib_build" python=3.4 numpy python-dateutil pyparsing pytz tornado "cycler>=0.10" tk libpng zlib freetype -activate matplotlib_build -# if you want a qt backend, you also have to install pyqt (be aware that pyqt doesn't mix well if -# you have created the environment with conda-forge already activated...) -conda install pyqt -# this package is only available in the conda-forge channel -conda install -c conda-forge msinttypes -# for python 2.7 -conda install -c conda-forge backports.functools_lru_cache - -# copy the libs which have "wrong" names -set LIBRARY_LIB=%CONDA_DEFAULT_ENV%\Library\lib -mkdir lib || cmd /c "exit /b 0" -copy %LIBRARY_LIB%\zlibstatic.lib lib\z.lib -copy %LIBRARY_LIB%\libpng_static.lib lib\png.lib - -# Make the header files and the rest of the static libs available during the build -# CONDA_DEFAULT_ENV is a env variable which is set to the currently active environment path -set MPLBASEDIRLIST=%CONDA_DEFAULT_ENV%\Library\;. - -# build the wheel -python setup.py bdist_wheel -``` - -The `build_alllocal.cmd` script automates these steps if you already created and activated the conda environment. - - -## Conda packages - -This needs a [working installed C compiler](http://blog.ionelmc.ro/2014/12/21/compiling-python-extensions-on-windows/) -for the version of python you are compiling the package for but you don't need to setup the -environment variables. - -```sh -# only the first time... -conda install conda-build - -# the python version you want a package for... -set CONDA_PY=3.5 - -# builds the package, using a clean build environment -conda build ci\conda_recipe - -# install the new package -conda install --use-local matplotlib -``` From b55412ef1297c9965e8e416af8375ad50d978e60 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Sat, 11 Mar 2017 14:12:14 -0800 Subject: [PATCH 02/13] DOC improved our installation documentation --- INSTALL | 260 ++++++++++++++++++++------------------------------------ 1 file changed, 90 insertions(+), 170 deletions(-) diff --git a/INSTALL b/INSTALL index 8f757db54e5d..c77f13863c06 100644 --- a/INSTALL +++ b/INSTALL @@ -7,58 +7,57 @@ Installing ========== -There are many different ways to install matplotlib, and the best way -depends on what operating system you are using, what you already have -installed, and how you want to use it. To avoid wading through all -the details (and potential complications) on this page, there are several -convenient options. +.. note:: -Installing pre-built packages -============================= + If you wish to contribute to the project, it's recommended you + :ref:`install the latest development version`. -Most platforms : scientific Python distributions ------------------------------------------------- -The first option is to use one of the pre-packaged python -distributions that already provide matplotlib built-in. The -Continuum.io Python distribution (`Anaconda -`_ or `miniconda -`_) and the Enthought -distribution `(Canopy) `_ -are both excellent choices that "just work" out of the box for -Windows, OSX and common Linux platforms. Both of these distributions -include matplotlib and *lots* of other useful tools. +.. contents.. + +Installing an official release +============================== + +Matplotlib and most of its dependencies all available as wheel packages for +OSX, windows and many linux distributions:: + + pip install -U numpy scipy scikit-learn + +Third-party distributions of Matplotlib +======================================= + +Scientific Python distributions: Conda, Canopy... +-------------------------------------------------- + +The first option is to use one of the pre-packaged Python distributions that +already provide Matplotlib built-in. Both `Anaconda +`_ and `Canopy +`_ are both excellent choices that +"just work" out of the box for Windows, OSX and common Linux platforms. Both +of these distributions include Matplotlib and *lots* of other useful tools. Linux : using your package manager ---------------------------------- -If you are on Linux, you might prefer to use your package manager. matplotlib +If you are on Linux, you might prefer to use your package manager. Matplotlib is packaged for almost every major Linux distribution. * Debian / Ubuntu : ``sudo apt-get install python-matplotlib`` * Fedora / Redhat : ``sudo yum install python-matplotlib`` -Mac OSX : using pip -------------------- - -If you are on Mac OSX you can probably install matplotlib binaries using the -standard Python installation program pip_. -See :ref:`install_osx_binaries`. - .. _installing_windows: Windows ------- -If you don't already have Python installed, we recommend using -one of the `scipy-stack compatible Python distributions +We strongly recommend using `scipy-stack compatible Python distributions `_ such as WinPython, Python(x,y), -Enthought Canopy, or Continuum Anaconda, which have matplotlib and many -of its dependencies, plus other useful packages, preinstalled. +Enthought Canopy, or Continuum Anaconda, which have Matplotlib and many of its +dependencies, plus other useful packages, preinstalled. For `standard Python `_ installations, -install matplotlib using pip_:: +install Matplotlib using pip_:: python -m pip install -U pip setuptools python -m pip install matplotlib @@ -103,7 +102,7 @@ for the official binaries. GTK3 is not supported on Windows. The Windows wheels (:file:`*.whl`) on the `PyPI download page `_ do not contain test data or example code. -If you want to try the many demos that come in the matplotlib source +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: @@ -123,12 +122,12 @@ To run the test suite: Installing from source ====================== -If you are interested in contributing to matplotlib development, +If you are interested in contributing to Matplotlib development, running the latest source code, or just like to build everything -yourself, it is not difficult to build matplotlib from source. Grab +yourself, it is not difficult to build Matplotlib from source. Grab the latest *tar.gz* release file from `the PyPI files page `_, or if you want to -develop matplotlib or just need the latest bugfixed version, grab the +develop Matplotlib or just need the latest bugfixed version, grab the latest git version :ref:`install-from-git`. The standard environment variables `CC`, `CXX`, `PKG_CONFIG` are respected. @@ -141,7 +140,7 @@ cross compiling. export PKG_CONFIG=x86_64-pc-linux-gnu-pkg-config Once you have satisfied the requirements detailed below (mainly -python, numpy, libpng and freetype), you can build matplotlib. +python, numpy, libpng and freetype), you can build Matplotlib. :: cd matplotlib @@ -152,12 +151,12 @@ We provide a `setup.cfg `_ file that goes with :file:`setup.py` which you can use to customize the build process. For example, which default backend to use, whether -some of the optional libraries that matplotlib ships with are +some of the optional libraries that Matplotlib ships with are installed, and so on. This file will be particularly useful to those -packaging matplotlib. +packaging Matplotlib. If you have installed prerequisites to nonstandard places and need to -inform matplotlib where they are, edit ``setupext.py`` and add the base +inform Matplotlib where they are, edit ``setupext.py`` and add the base dirs to the ``basedir`` dictionary entry for your ``sys.platform``. e.g., if the header to some required library is in ``/some/path/include/someheader.h``, put ``/some/path`` in the @@ -165,132 +164,53 @@ e.g., if the header to some required library is in .. _install_requirements: -Build requirements ------------------- - -These are external packages which you will need to install before -installing matplotlib. If you are building on OSX, see -:ref:`build_osx`. If you are building on Windows, see -:ref:`build_windows`. If you are installing dependencies with a -package manager on Linux, you may need to install the development -packages (look for a "-dev" postfix) in addition to the libraries -themselves. - - -Required Dependencies -^^^^^^^^^^^^^^^^^^^^^ - -:term:`python` 2.7, 3.4, 3.5 or 3.6 - `Download python `_. - -:term:`numpy` |minimum_numpy_version| (or later) - array support for python (`download numpy `_) - -`setuptools `__ - Setuptools provides extensions for python package installation. - -:term:`dateutil` 1.1 or later - Provides extensions to python datetime handling. If using pip, - easy_install or installing from source, the installer will attempt - to download and install `python_dateutil` from PyPI. - -`pyparsing `__ - Required for matplotlib's mathtext math rendering support. If - using pip, easy_install or installing from source, the installer - will attempt to download and install `pyparsing` from PyPI. - -`libpng 1.2 (or later) `__ - library for loading and saving :term:`PNG` files (`download - `__). libpng requires - zlib. - -`pytz `__ - Used to manipulate time-zone aware datetimes. - https://pypi.python.org/pypi/pytz - -:term:`FreeType` 2.3 or later - Library for reading true type font files. If using pip, easy_install or - installing from source, the installer will attempt to locate FreeType in - expected locations. If it cannot, try installing `pkg-config - `__, - a tool used to find required non-python libraries. - -`cycler `__ 0.10.0 or later - Composable cycle class used for constructing style-cycles - -`six `_ - Required for compatibility between python 2 and python 3 - - -Dependencies for python 2 -^^^^^^^^^^^^^^^^^^^^^^^^^ - -`backports.functools_lru_cache `_ - Required for compatibility if running on Python 2.7. - -`subprocess32 `_ - Optional, unix only. Backport of the subprocess standard library from 3.2+ - for Python 2.7. It provides better error messages and timeout support. - -Optional GUI framework -^^^^^^^^^^^^^^^^^^^^^^ - -These are optional packages which you may want to install to use -matplotlib with a user interface toolkit. See -:ref:`what-is-a-backend` for more details on the optional matplotlib -backends and the capabilities they provide. - -:term:`tk` 8.3 or later, not 8.6.0 or 8.6.1 - The TCL/Tk widgets library used by the TkAgg backend. - - Versions 8.6.0 and 8.6.1 are known to have issues that may result - in segfaults when closing multiple windows in the wrong order. - -:term:`pyqt` 4.4 or later - The Qt4 widgets library python wrappers for the Qt4Agg backend - -:term:`pygtk` 2.4 or later - The python wrappers for the GTK widgets library for use with the - GTK or GTKAgg backend - -:term:`wxpython` 2.8 or later - The python wrappers for the wx widgets library for use with the - WX or WXAgg backend - -Optional external programs -^^^^^^^^^^^^^^^^^^^^^^^^^^ -`ffmpeg `__/`avconv `__ or `mencoder `__ - Required for the animation module to be save out put to movie - formats. - -`ImageMagick `__ - Required for the animation module to be able to save to animated gif. - -Optional dependencies -^^^^^^^^^^^^^^^^^^^^^ - -`Pillow `__ - If Pillow is installed, matplotlib can read and write a larger - selection of image file formats. - -`pkg-config `__ - A tool used to find required non-python libraries. This is not strictly - required, but can make installation go more smoothly if the libraries and - headers are not in the expected locations. - - -Required libraries that ship with matplotlib -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:term:`agg` 2.4 - The antigrain C++ rendering engine. matplotlib links against the - agg template source statically, so it will not affect anything on - your system outside of matplotlib. - -`qhull` 2012.1 - A library for computing Delaunay triangulations. - -`ttconv` - truetype font utility +Dependencies +------------ + +Matplotlib requires a large number of dependencies: + + * `Python `_ (>= 2.7 or >= 3.4) + * `numpy `_ (>= |minimum_numpy_version|) + * `setuptools `__ + * `dateutil` (>= 1.1) + * `pyparsing `__ + * `libpng `__ ( >= 1.2) + * `pytz `__ + * FreeType` (>= 2.3) + * `cycler `__ (>= 0.10.0) + * `six `_ + * `backports.functools_lru_cache `_ + (for Python 2.7 only) + * `subprocess32 `_ (for Python + 2.7 only) + +Optionally, you can also install a number of packages to enables better user +interface toolkit. 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; + * :term:`pyqt` (>= 4.4): for the Qt4Agg backend; + * :term:`pygtk` (>= 2.4): for the GTK and the GTKAgg backend; + * :term:`wxpython` (>= 2.8 or later): for the WX or WXAgg backend. + +For better support of animation output format and image file format, you can +install the following: + + * `ffmpeg `__/`avconv + `__ or `mencoder + `__ (for saving movies); + * `ImageMagick `__ (for saving + animated gifs); + * `Pillow `__ (for a larger selection of image + file format). + +.. note:: + + Matplotlib depends on a large number of non-python libraries. + `pkg-config `__ + can be used to find required non-python libraries and thus make install go + more smoothly if the libraries and headers are not in the expected + locations. .. _build_linux: @@ -301,17 +221,17 @@ Building on Linux It is easiest to use your system package manager to install the dependencies. If you are on Debian/Ubuntu, you can get all the dependencies -required to build matplotlib with:: +required to build Matplotlib with:: sudo apt-get build-dep python-matplotlib If you are on Fedora/RedHat, you can get all the dependencies required -to build matplotlib by first installing ``yum-builddep`` and then +to build Matplotlib by first installing ``yum-builddep`` and then running:: su -c "yum-builddep python-matplotlib" -This does not build matplotlib, but it does get and install the +This does not build Matplotlib, but it does get and install the build dependencies, which will make building from source easier. @@ -340,7 +260,7 @@ Example usage:: port install libpng freetype pkgconfig -To install matplotlib from source, execute: +To install Matplotlib from source, execute: Example usage:: @@ -387,7 +307,7 @@ how to install and setup such environments. If in doubt: use python 3.5 as it mo without fiddling with environment variables:: # create a new environment with the required packages - conda create -n "matplotlib_build" python=3.4 numpy python-dateutil pyparsing pytz tornado "cycler>=0.10" tk libpng zlib freetype + conda create -n "matplotlib_build" python=3.5 numpy python-dateutil pyparsing pytz tornado "cycler>=0.10" tk libpng zlib freetype activate matplotlib_build # if you want a qt backend, you also have to install pyqt (be aware that pyqt doesn't mix well if # you have created the environment with conda-forge already activated...) From 3044d12cd47883305ede29ea32cc90217a6efab6 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Sat, 11 Mar 2017 14:38:39 -0800 Subject: [PATCH 03/13] DOC Completed the list of optional dependencies --- INSTALL | 61 ++++++++++++++++++++++++++++++++------------------------- 1 file changed, 34 insertions(+), 27 deletions(-) diff --git a/INSTALL b/INSTALL index c77f13863c06..736659bb164c 100644 --- a/INSTALL +++ b/INSTALL @@ -22,7 +22,7 @@ Installing an official release Matplotlib and most of its dependencies all available as wheel packages for OSX, windows and many linux distributions:: - pip install -U numpy scipy scikit-learn + pip install -U matplotlib Third-party distributions of Matplotlib ======================================= @@ -73,28 +73,9 @@ or `32 bit `__ for Python 3.4) redistributable packages need to be installed. -Matplotlib depends on `Pillow `_ -for reading and saving JPEG, BMP, and TIFF image files. -Matplotlib requires `MiKTeX `_ and -`GhostScript `_ for rendering text -with LaTeX. -`FFmpeg `_, `avconv `_, -`mencoder `_, or -`ImageMagick `_ are required for the -animation module. The following backends should work out of the box: agg, tkagg, ps, pdf and svg. -For other backends you may need to install -`pycairo `_, -`PyQt4 `_, -`PyQt5 `_, -`PySide `_, -`wxPython `_, -`PyGTK `_, -`Tornado `_, -or GhostScript. - TkAgg is probably the best backend for interactive use from the standard Python shell or IPython. It is enabled as the default backend for the official binaries. GTK3 is not supported on Windows. @@ -115,6 +96,17 @@ To run the test suite: `_; * run ``py.test path\\to\\tests\\directory``. +.. note:: + + The following backends work out of the box: Agg, TkAgg, ps, pdf and svg. + TkAgg is probably the best backend for interactive use from the standard + Python shell or from IPython and is enabled as default. + + GTK3 is not supported on windows. + + For support for other backend, LaTeX rendering, animation input/output and + larger selection of file format, you may need to install `additional + dependencies <_install_requirements>`. .. _install_from_source: @@ -176,24 +168,30 @@ Matplotlib requires a large number of dependencies: * `pyparsing `__ * `libpng `__ ( >= 1.2) * `pytz `__ - * FreeType` (>= 2.3) + * FreeType (>= 2.3) * `cycler `__ (>= 0.10.0) * `six `_ * `backports.functools_lru_cache `_ (for Python 2.7 only) * `subprocess32 `_ (for Python - 2.7 only) + 2.7 only, on Linux and mac os X only) Optionally, you can also install a number of packages to enables better user interface toolkit. 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; - * :term:`pyqt` (>= 4.4): for the Qt4Agg backend; + * `PyQt4 `_ (>= 4.4): for the Qt4Agg backend; + * `PyQt5 `_: for the Qt5Agg backend; * :term:`pygtk` (>= 2.4): for the GTK and the GTKAgg backend; - * :term:`wxpython` (>= 2.8 or later): for the WX or WXAgg backend. - -For better support of animation output format and image file format, you can + * :term:`wxpython` (>= 2.8 or later): for the WX or WXAgg backend; + * `pycairo `_; + * `PySide `_; + * `PyGTK `_; + * `Tornado `_: for the WebAgg backend. + +For better support of animation output format and image file format, LaTeX, +etc you can install the following: * `ffmpeg `__/`avconv @@ -202,7 +200,9 @@ install the following: * `ImageMagick `__ (for saving animated gifs); * `Pillow `__ (for a larger selection of image - file format). + file format: JPEG, BMP, and TIFF image files); + * `Latex `_ and `GhostScript `_ + (for rendering text with LaTeX); .. note:: @@ -212,6 +212,13 @@ install the following: more smoothly if the libraries and headers are not in the expected locations. +.. note:: + + The following libraries are shipped with Matplotlib: + + - `Agg`: the antigrain C++ rendering engine; + - `qhull`: to compute Delaunay triangulation; + - `ttconv`: a true type font utility. .. _build_linux: From 60a1b646a5151df3156f59eda2343022cd14bac6 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Sat, 11 Mar 2017 15:06:30 -0800 Subject: [PATCH 04/13] MAINT renamed INSTALL into INSTALL.rst for rendering --- INSTALL => INSTALL.rst | 0 doc/make.py | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename INSTALL => INSTALL.rst (100%) diff --git a/INSTALL b/INSTALL.rst similarity index 100% rename from INSTALL rename to INSTALL.rst diff --git a/doc/make.py b/doc/make.py index 86aae03e8ba6..fe07c40c2b86 100755 --- a/doc/make.py +++ b/doc/make.py @@ -224,7 +224,7 @@ def build_all(): # Change directory to the one containing this file current_dir = os.getcwd() os.chdir(os.path.dirname(os.path.join(current_dir, __file__))) -copy_if_out_of_date('../INSTALL', 'users/installing.rst') +copy_if_out_of_date('../INSTALL.rst', 'users/installing.rst') # Create the examples symlink, if it doesn't exist From 36a917c28b22db3a2ba5ed0a4585c31e0aae538f Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Thu, 16 Mar 2017 12:19:33 -0700 Subject: [PATCH 05/13] DOC fix typos and minor detail in installation.rst --- INSTALL.rst | 55 +++++++++++++++++++++-------------------------------- 1 file changed, 22 insertions(+), 33 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index 736659bb164c..913457d308f8 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -1,6 +1,7 @@ -.. The source of this document is INSTALL. During the doc build process, +.. The source of this document is INSTALL.rst. During the doc build process, .. this file is copied over to doc/users/installing.rst. -.. Therefore, you must edit INSTALL, *not* doc/users/installing.rst! +.. Therefore, you must edit INSTALL.rst, *not* doc/users/installing.rst! + .. _pip: https://pypi.python.org/pypi/pip/ ========== @@ -19,8 +20,8 @@ Installing Installing an official release ============================== -Matplotlib and most of its dependencies all available as wheel packages for -OSX, windows and many linux distributions:: +Matplotlib and most of its dependencies arr all available as wheel packages for +OSX, windows and Linux distributions:: pip install -U matplotlib @@ -28,7 +29,7 @@ Third-party distributions of Matplotlib ======================================= Scientific Python distributions: Conda, Canopy... --------------------------------------------------- +------------------------------------------------- The first option is to use one of the pre-packaged Python distributions that already provide Matplotlib built-in. Both `Anaconda @@ -43,8 +44,9 @@ 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. -* Debian / Ubuntu : ``sudo apt-get install python-matplotlib`` -* Fedora / Redhat : ``sudo yum install python-matplotlib`` +* Debian / Ubuntu: ``sudo apt-get install python-matplotlib`` +* Fedora / Red Hat: ``sudo yum install python-matplotlib`` +* Arch: ``sudo pacman -S python-matplotlib`` .. _installing_windows: @@ -53,7 +55,7 @@ Windows We strongly recommend using `scipy-stack compatible Python distributions `_ such as WinPython, Python(x,y), -Enthought Canopy, or Continuum Anaconda, which have Matplotlib and many of its +Enthought Canopy, or Continuum Anaconda, which have Matplotlib and its dependencies, plus other useful packages, preinstalled. For `standard Python `_ installations, @@ -74,12 +76,6 @@ or for Python 3.4) redistributable packages need to be installed. -The following backends should work out of the box: agg, tkagg, ps, -pdf and svg. -TkAgg is probably the best backend for interactive use from the -standard Python shell or IPython. It is enabled as the default backend -for the official binaries. GTK3 is not supported on Windows. - The Windows wheels (:file:`*.whl`) on the `PyPI download page `_ do not contain test data or example code. @@ -94,7 +90,7 @@ To run the test suite: `mock `_, Pillow, MiKTeX, GhostScript, ffmpeg, avconv, mencoder, ImageMagick, and `Inkscape `_; - * run ``py.test path\\to\\tests\\directory``. + * run ``py.test path\to\tests\directory``. .. note:: @@ -149,7 +145,7 @@ packaging Matplotlib. If you have installed prerequisites to nonstandard places and need to inform Matplotlib where they are, edit ``setupext.py`` and add the base -dirs to the ``basedir`` dictionary entry for your ``sys.platform``. +dirs to the ``basedir`` dictionary entry for your ``sys.platform``; e.g., if the header to some required library is in ``/some/path/include/someheader.h``, put ``/some/path`` in the ``basedir`` list for your platform. @@ -174,7 +170,7 @@ Matplotlib requires a large number of dependencies: * `backports.functools_lru_cache `_ (for Python 2.7 only) * `subprocess32 `_ (for Python - 2.7 only, on Linux and mac os X only) + 2.7 only, on Linux and Mac OSX only) Optionally, you can also install a number of packages to enables better user interface toolkit. See :ref:`what-is-a-backend` for more details on the @@ -185,12 +181,11 @@ optional Matplotlib backends and the capabilities they provide. * `PyQt5 `_: for the Qt5Agg backend; * :term:`pygtk` (>= 2.4): for the GTK and the GTKAgg backend; * :term:`wxpython` (>= 2.8 or later): for the WX or WXAgg backend; - * `pycairo `_; - * `PySide `_; - * `PyGTK `_; + * `pycairo `_: for gtk3cairo; + * `PySide `_: for the qt4Agg; * `Tornado `_: for the WebAgg backend. -For better support of animation output format and image file format, LaTeX, +For better support of animation output format and image file formats, LaTeX, etc you can install the following: @@ -249,27 +244,21 @@ Building on OSX The build situation on OSX is complicated by the various places one can get the libpng and freetype requirements (darwinports, fink, -/usr/X11R6) and the different architectures (e.g., x86, ppc, universal) and +/usr/X11R6) and the different architectures (e.g., x86, ppc, universal), the different OSX version (e.g., 10.4 and 10.5). We recommend that you build the way we do for the OSX release: get the source from the tarball or the git repository and install the required dependencies through a third-party -package manager: two widely used package managers are homebrew, and MacPorts. +package manager. Two widely used package managers are homebrew, and MacPorts. The following example illustrates how to install libpng and freetype using -brew: - -Example usage:: +brew:: brew install libpng freetype pkg-config -If you are using MacPorts, execute the following instead: - -Example usage:: +If you are using MacPorts, execute the following instead:: port install libpng freetype pkgconfig -To install Matplotlib from source, execute: - -Example usage:: +To install Matplotlib from source, execute:: python setup.py install @@ -310,7 +299,7 @@ install. The commands below assume that you can compile a native python lib for the python version of your choice. See `this howto `_ -how to install and setup such environments. If in doubt: use python 3.5 as it mostly works +how to install and setup such environments. If in doubt: use Python >= 3.5 as it mostly works without fiddling with environment variables:: # create a new environment with the required packages From f55ed17f2c7da976d712e763e6aaf2824fab79b5 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 16 Mar 2017 18:46:05 -0400 Subject: [PATCH 06/13] Use more https in install docs. --- INSTALL.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index 913457d308f8..fd48c359f4c3 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -54,7 +54,7 @@ Windows ------- We strongly recommend using `scipy-stack compatible Python distributions -`_ such as WinPython, Python(x,y), +`_ such as WinPython, Python(x,y), Enthought Canopy, or Continuum Anaconda, which have Matplotlib and its dependencies, plus other useful packages, preinstalled. @@ -191,10 +191,10 @@ install the following: * `ffmpeg `__/`avconv `__ or `mencoder - `__ (for saving movies); - * `ImageMagick `__ (for saving + `__ (for saving movies); + * `ImageMagick `__ (for saving animated gifs); - * `Pillow `__ (for a larger selection of image + * `Pillow `__ (for a larger selection of image file format: JPEG, BMP, and TIFF image files); * `Latex `_ and `GhostScript `_ (for rendering text with LaTeX); @@ -298,7 +298,7 @@ requirements (png, freetype,...) are statically linked and therefore not needed install. The commands below assume that you can compile a native python lib for the python version of your -choice. See `this howto `_ +choice. See `this howto `_ how to install and setup such environments. If in doubt: use Python >= 3.5 as it mostly works without fiddling with environment variables:: @@ -333,9 +333,8 @@ you already created and activated the conda environment. Conda packages ^^^^^^^^^^^^^^ -This needs a `working installed C -compiler -`_ +This needs a `working installed C compiler +`_ for the version of python you are compiling the package for but you don't need to setup the environment variables:: From 37af9a610ba0824dd7fc906da4f63e9247643338 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 16 Mar 2017 19:22:37 -0400 Subject: [PATCH 07/13] Use consistent capitalization in install instructions. --- INSTALL.rst | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index fd48c359f4c3..5d9bd85220f0 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -21,7 +21,7 @@ Installing an official release ============================== Matplotlib and most of its dependencies arr all available as wheel packages for -OSX, windows and Linux distributions:: +OSX, Windows and Linux distributions:: pip install -U matplotlib @@ -53,7 +53,7 @@ is packaged for almost every major Linux distribution. Windows ------- -We strongly recommend using `scipy-stack compatible Python distributions +We strongly recommend using `SciPy-stack compatible Python distributions `_ such as WinPython, Python(x,y), Enthought Canopy, or Continuum Anaconda, which have Matplotlib and its dependencies, plus other useful packages, preinstalled. @@ -98,7 +98,7 @@ To run the test suite: TkAgg is probably the best backend for interactive use from the standard Python shell or from IPython and is enabled as default. - GTK3 is not supported on windows. + GTK3 is not supported on Windows. For support for other backend, LaTeX rendering, animation input/output and larger selection of file format, you may need to install `additional @@ -128,7 +128,7 @@ cross compiling. export PKG_CONFIG=x86_64-pc-linux-gnu-pkg-config Once you have satisfied the requirements detailed below (mainly -python, numpy, libpng and freetype), you can build Matplotlib. +Python, NumPy, libpng and FreeType), you can build Matplotlib. :: cd matplotlib @@ -158,11 +158,11 @@ Dependencies Matplotlib requires a large number of dependencies: * `Python `_ (>= 2.7 or >= 3.4) - * `numpy `_ (>= |minimum_numpy_version|) + * `NumPy `_ (>= |minimum_numpy_version|) * `setuptools `__ * `dateutil` (>= 1.1) * `pyparsing `__ - * `libpng `__ ( >= 1.2) + * `libpng `__ (>= 1.2) * `pytz `__ * FreeType (>= 2.3) * `cycler `__ (>= 0.10.0) @@ -181,8 +181,8 @@ optional Matplotlib backends and the capabilities they provide. * `PyQt5 `_: for the Qt5Agg backend; * :term:`pygtk` (>= 2.4): for the GTK and the GTKAgg backend; * :term:`wxpython` (>= 2.8 or later): for the WX or WXAgg backend; - * `pycairo `_: for gtk3cairo; - * `PySide `_: for the qt4Agg; + * `pycairo `_: for GTK3Cairo; + * `PySide `_: for the Qt4Agg backend; * `Tornado `_: for the WebAgg backend. For better support of animation output format and image file formats, LaTeX, @@ -196,14 +196,14 @@ install the following: animated gifs); * `Pillow `__ (for a larger selection of image file format: JPEG, BMP, and TIFF image files); - * `Latex `_ and `GhostScript `_ + * `LaTeX `_ and `GhostScript `_ (for rendering text with LaTeX); .. note:: - Matplotlib depends on a large number of non-python libraries. + Matplotlib depends on a large number of non-Python libraries. `pkg-config `__ - can be used to find required non-python libraries and thus make install go + can be used to find required non-Python libraries and thus make install go more smoothly if the libraries and headers are not in the expected locations. @@ -211,7 +211,7 @@ install the following: The following libraries are shipped with Matplotlib: - - `Agg`: the antigrain C++ rendering engine; + - `Agg`: the Anti-Grain Geometry C++ rendering engine; - `qhull`: to compute Delaunay triangulation; - `ttconv`: a true type font utility. @@ -243,13 +243,13 @@ Building on OSX --------------- The build situation on OSX is complicated by the various places one -can get the libpng and freetype requirements (darwinports, fink, +can get the libpng and FreeType requirements (MacPorts, Fink, /usr/X11R6) and the different architectures (e.g., x86, ppc, universal), the different OSX version (e.g., 10.4 and 10.5). We recommend that you build the way we do for the OSX release: get the source from the tarball or the git repository and install the required dependencies through a third-party -package manager. Two widely used package managers are homebrew, and MacPorts. -The following example illustrates how to install libpng and freetype using +package manager. Two widely used package managers are Homebrew, and MacPorts. +The following example illustrates how to install libpng and FreeType using brew:: brew install libpng freetype pkg-config @@ -280,11 +280,11 @@ Visual Studio 2015 for 3.5 and 3.6. Python extensions are recommended to be com with the same compiler. Since there is no canonical Windows package manager, the methods for building -freetype, zlib, and libpng from source code are documented as a build script +FreeType, zlib, and libpng from source code are documented as a build script at `matplotlib-winbuild `_. -There are a few possibilities to build matplotlib on Windows: +There are a few possibilities to build Matplotlib on Windows: * Wheels via `matplotlib-winbuild `_ * Wheels by using conda packages @@ -294,10 +294,10 @@ Wheel builds using conda packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is a wheel build, but we use conda packages to get all the requirements. The binary -requirements (png, freetype,...) are statically linked and therefore not needed during the wheel +requirements (png, FreeType,...) are statically linked and therefore not needed during the wheel install. -The commands below assume that you can compile a native python lib for the python version of your +The commands below assume that you can compile a native Python lib for the Python version of your choice. See `this howto `_ how to install and setup such environments. If in doubt: use Python >= 3.5 as it mostly works without fiddling with environment variables:: @@ -310,7 +310,7 @@ without fiddling with environment variables:: conda install pyqt # this package is only available in the conda-forge channel conda install -c conda-forge msinttypes - # for python 2.7 + # for Python 2.7 conda install -c conda-forge backports.functools_lru_cache # copy the libs which have "wrong" names @@ -335,13 +335,13 @@ Conda packages This needs a `working installed C compiler `_ -for the version of python you are compiling the package for but you don't need +for the version of Python you are compiling the package for but you don't need to setup the environment variables:: # only the first time... conda install conda-build - # the python version you want a package for... + # the Python version you want a package for... set CONDA_PY=3.5 # builds the package, using a clean build environment From 8ee8a93bd284da57f4401ec71d89b5c0a284560c Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 16 Mar 2017 19:24:00 -0400 Subject: [PATCH 08/13] Use dnf for Fedora install instructions. --- INSTALL.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index 5d9bd85220f0..08ac7012f1c2 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -45,7 +45,8 @@ If you are on Linux, you might prefer to use your package manager. Matplotlib is packaged for almost every major Linux distribution. * Debian / Ubuntu: ``sudo apt-get install python-matplotlib`` -* Fedora / Red Hat: ``sudo yum install python-matplotlib`` +* Fedora: ``sudo dnf install python-matplotlib`` +* Red Hat: ``sudo yum install python-matplotlib`` * Arch: ``sudo pacman -S python-matplotlib`` .. _installing_windows: @@ -227,9 +228,13 @@ required to build Matplotlib with:: sudo apt-get build-dep python-matplotlib -If you are on Fedora/RedHat, you can get all the dependencies required -to build Matplotlib by first installing ``yum-builddep`` and then -running:: +If you are on Fedora, you can get all the dependencies required to build +Matplotlib with:: + + sudo dnf builddep python-matplotlib + +If you are on RedHat, you can get all the dependencies required to build +Matplotlib by first installing ``yum-builddep`` and then running:: su -c "yum-builddep python-matplotlib" From 11590852e4a1d2486c2d0ff5f7b580d04fcc494a Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 16 Mar 2017 19:28:33 -0400 Subject: [PATCH 09/13] Rename OSX to macOS for install instructions. --- INSTALL.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index 08ac7012f1c2..d395791e9e97 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -21,7 +21,7 @@ Installing an official release ============================== Matplotlib and most of its dependencies arr all available as wheel packages for -OSX, Windows and Linux distributions:: +macOS, Windows and Linux distributions:: pip install -U matplotlib @@ -35,7 +35,7 @@ The first option is to use one of the pre-packaged Python distributions that already provide Matplotlib built-in. Both `Anaconda `_ and `Canopy `_ are both excellent choices that -"just work" out of the box for Windows, OSX and common Linux platforms. Both +"just work" out of the box for Windows, macOS and common Linux platforms. Both of these distributions include Matplotlib and *lots* of other useful tools. Linux : using your package manager @@ -171,7 +171,7 @@ Matplotlib requires a large number of dependencies: * `backports.functools_lru_cache `_ (for Python 2.7 only) * `subprocess32 `_ (for Python - 2.7 only, on Linux and Mac OSX only) + 2.7 only, on Linux and macOS only) Optionally, you can also install a number of packages to enables better user interface toolkit. See :ref:`what-is-a-backend` for more details on the @@ -244,14 +244,14 @@ build dependencies, which will make building from source easier. .. _build_osx: -Building on OSX ---------------- +Building on macOS +----------------- -The build situation on OSX is complicated by the various places one +The build situation on macOS is complicated by the various places one can get the libpng and FreeType requirements (MacPorts, Fink, /usr/X11R6) and the different architectures (e.g., x86, ppc, universal), -the different OSX version (e.g., 10.4 and 10.5). We recommend that you build -the way we do for the OSX release: get the source from the tarball or the +the different macOS version (e.g., 10.4 and 10.5). We recommend that you build +the way we do for the macOS release: get the source from the tarball or the git repository and install the required dependencies through a third-party package manager. Two widely used package managers are Homebrew, and MacPorts. The following example illustrates how to install libpng and FreeType using From 86be6848d284d0fe320ebb7ff1c08d376cb17956 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 16 Mar 2017 19:37:54 -0400 Subject: [PATCH 10/13] Tweak phrasing of install instructions. --- INSTALL.rst | 55 ++++++++++++++++++++++++++--------------------------- README.rst | 4 ++-- 2 files changed, 29 insertions(+), 30 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index d395791e9e97..08562b1fd185 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -14,17 +14,17 @@ Installing :ref:`install the latest development version`. - -.. contents.. +.. contents.. Installing an official release ============================== -Matplotlib and most of its dependencies arr all available as wheel packages for +Matplotlib and most of its dependencies are all available as wheel packages for macOS, Windows and Linux distributions:: pip install -U matplotlib + Third-party distributions of Matplotlib ======================================= @@ -101,9 +101,9 @@ To run the test suite: GTK3 is not supported on Windows. - For support for other backend, LaTeX rendering, animation input/output and - larger selection of file format, you may need to install `additional - dependencies <_install_requirements>`. + For support for other backends, LaTeX rendering, animation input/output and + a larger selection of file formats, you may need to install `additional + dependencies <_install_requirements>`_. .. _install_from_source: @@ -147,7 +147,7 @@ packaging Matplotlib. If you have installed prerequisites to nonstandard places and need to inform Matplotlib where they are, edit ``setupext.py`` and add the base dirs to the ``basedir`` dictionary entry for your ``sys.platform``; -e.g., if the header to some required library is in +e.g., if the header of some required library is in ``/some/path/include/someheader.h``, put ``/some/path`` in the ``basedir`` list for your platform. @@ -161,7 +161,7 @@ Matplotlib requires a large number of dependencies: * `Python `_ (>= 2.7 or >= 3.4) * `NumPy `_ (>= |minimum_numpy_version|) * `setuptools `__ - * `dateutil` (>= 1.1) + * dateutil (>= 1.1) * `pyparsing `__ * `libpng `__ (>= 1.2) * `pytz `__ @@ -173,22 +173,21 @@ Matplotlib requires a large number of dependencies: * `subprocess32 `_ (for Python 2.7 only, on Linux and macOS only) -Optionally, you can also install a number of packages to enables better user -interface toolkit. See :ref:`what-is-a-backend` for more details on the +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 `_ (>= 4.4): for the Qt4Agg backend; + * `PyQt4 `_ (>= 4.4) or + `PySide `_: for the Qt4Agg backend; * `PyQt5 `_: for the Qt5Agg backend; * :term:`pygtk` (>= 2.4): for the GTK and the GTKAgg backend; * :term:`wxpython` (>= 2.8 or later): for the WX or WXAgg backend; * `pycairo `_: for GTK3Cairo; - * `PySide `_: for the Qt4Agg backend; * `Tornado `_: for the WebAgg backend. For better support of animation output format and image file formats, LaTeX, -etc you can -install the following: +etc., you can install the following: * `ffmpeg `__/`avconv `__ or `mencoder @@ -196,7 +195,7 @@ install the following: * `ImageMagick `__ (for saving animated gifs); * `Pillow `__ (for a larger selection of image - file format: JPEG, BMP, and TIFF image files); + file formats: JPEG, BMP, and TIFF image files); * `LaTeX `_ and `GhostScript `_ (for rendering text with LaTeX); @@ -204,8 +203,8 @@ install the following: Matplotlib depends on a large number of non-Python libraries. `pkg-config `__ - can be used to find required non-Python libraries and thus make install go - more smoothly if the libraries and headers are not in the expected + 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. .. note:: @@ -238,7 +237,7 @@ Matplotlib by first installing ``yum-builddep`` and then running:: su -c "yum-builddep python-matplotlib" -This does not build Matplotlib, but it does get and install the +These commands do not build Matplotlib, but instead get and install the build dependencies, which will make building from source easier. @@ -249,13 +248,13 @@ Building on macOS The build situation on macOS is complicated by the various places one can get the libpng and FreeType requirements (MacPorts, Fink, -/usr/X11R6) and the different architectures (e.g., x86, ppc, universal), -the different macOS version (e.g., 10.4 and 10.5). We recommend that you build +/usr/X11R6), the different architectures (e.g., x86, ppc, universal), and +the different macOS versions (e.g., 10.4 and 10.5). We recommend that you build the way we do for the macOS release: get the source from the tarball or the git repository and install the required dependencies through a third-party package manager. Two widely used package managers are Homebrew, and MacPorts. The following example illustrates how to install libpng and FreeType using -brew:: +``brew``:: brew install libpng freetype pkg-config @@ -263,14 +262,14 @@ If you are using MacPorts, execute the following instead:: port install libpng freetype pkgconfig -To install Matplotlib from source, execute:: +After installing the above requirements, install Matplotlib from source by +executing:: python setup.py install - -Note that your environment is somewhat important. Some conda users have -found that, to run the tests, their PYTHONPATH must include -/path/to/anaconda/.../site-packages and their DYLD_FALLBACK_LIBRARY_PATH +Note that your environment is somewhat important. Some conda users have +found that, to run the tests, their PYTHONPATH must include +/path/to/anaconda/.../site-packages and their DYLD_FALLBACK_LIBRARY_PATH must include /path/to/anaconda/lib. @@ -304,7 +303,7 @@ install. The commands below assume that you can compile a native Python lib for the Python version of your choice. See `this howto `_ -how to install and setup such environments. If in doubt: use Python >= 3.5 as it mostly works +for how to install and setup such environments. If in doubt: use Python >= 3.5 as it mostly works without fiddling with environment variables:: # create a new environment with the required packages @@ -332,7 +331,7 @@ without fiddling with environment variables:: python setup.py bdist_wheel The `build_alllocal.cmd` script in the root folder automates these steps if -you already created and activated the conda environment. +you have already created and activated the conda environment. Conda packages diff --git a/README.rst b/README.rst index 4f8615cb8d3a..d00bb133c2c5 100644 --- a/README.rst +++ b/README.rst @@ -26,13 +26,13 @@ Matplotlib Matplotlib is a Python 2D plotting library which produces publication-quality figures in a variety of hardcopy formats and interactive environments across platforms. Matplotlib can be used in Python scripts, the Python and IPython -shell (ala MATLAB or Mathematica), web application servers, and various +shell (à la MATLAB or Mathematica), web application servers, and various graphical user interface toolkits. `Home page `_ Installation -============= +============ For installation instructions and requirements, see the INSTALL file or the `install `_ documentation. If you From 9265b4a352b1a6bd16e89287e020afb5e013cea2 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 16 Mar 2017 21:13:42 -0400 Subject: [PATCH 11/13] DOC: Fix broken cross-reference. --- INSTALL.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index 08562b1fd185..3857c6a87cce 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -102,8 +102,8 @@ To run the test suite: GTK3 is not supported on Windows. For support for other backends, LaTeX rendering, animation input/output and - a larger selection of file formats, you may need to install `additional - dependencies <_install_requirements>`_. + a larger selection of file formats, you may need to install :ref:`additional + dependencies `. .. _install_from_source: From bafe158ba989f52db8f081b04806b952f14182ac Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Sun, 19 Mar 2017 12:27:08 -0700 Subject: [PATCH 12/13] FIX table of contents on INSTALL.rst .. contents.. -> .. contents:: --- INSTALL.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/INSTALL.rst b/INSTALL.rst index 3857c6a87cce..245a0e9ae223 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -14,7 +14,7 @@ Installing :ref:`install the latest development version`. -.. contents.. +.. contents:: Installing an official release ============================== From dd08c3b6ec1de6ad34a0a99d7db37e9ca002d98c Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Mon, 20 Mar 2017 12:09:01 -0700 Subject: [PATCH 13/13] DOC fix README refers to INSTALL.rst --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index d00bb133c2c5..553ec7ec279e 100644 --- a/README.rst +++ b/README.rst @@ -34,7 +34,7 @@ graphical user interface toolkits. Installation ============ -For installation instructions and requirements, see the INSTALL file or the +For installation instructions and requirements, see the INSTALL.rst file or the `install `_ documentation. If you think you may want to contribute to matplotlib, check out the `guide to working with the source code