From 3b52f44562e2fe606786ffcec58fc7af80bc9929 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 19 Sep 2017 20:26:36 -0700 Subject: [PATCH 1/7] Update venv faq. The situation is much better: most GUI toolkits are now pip-installable. --- doc/faq/virtualenv_faq.rst | 101 +++++++++++++++++++++---------------- 1 file changed, 57 insertions(+), 44 deletions(-) diff --git a/doc/faq/virtualenv_faq.rst b/doc/faq/virtualenv_faq.rst index 37a60668d136..621f261adcb8 100644 --- a/doc/faq/virtualenv_faq.rst +++ b/doc/faq/virtualenv_faq.rst @@ -7,56 +7,69 @@ Working with Matplotlib in Virtual environments .. contents:: :backlinks: none - .. _virtualenv_introduction: Introduction ============ -When running :mod:`matplotlib` in a -`virtual environment `_ you may discover -a few issues. :mod:`matplotlib` itself has no issue with virtual environments. -However, the GUI frameworks that :mod:`matplotlib` uses for interactive -figures have some issues with virtual environments. Everything below assumes -some familiarity with the Matplotlib backends as found in :ref:`What is a -backend? `. +When running Matplotlib in a `virtual environment +`_ you may discover a few issues. +Matplotlib itself has no issue with virtual environments. However, some of +the external GUI frameworks that Matplotlib uses for interactive figures may +be tricky to install in a virtual environment. Everything below assumes some +familiarity with the Matplotlib backends as found in :ref:`What is a backend? +`. -If you only use the ``IPython/Jupyter Notebook``'s ``inline`` and ``notebook`` -backends and non interactive backends you should not have any issues and can +If you only use the IPython and Jupyter Notebook's ``inline`` and ``notebook`` +backends, or non-interactive backends, you should not have any issues and can ignore everything below. -If you are using Matplotlib on OSX you may also want to consider the -:ref:`OSX framework FAQ `. +Likewise, the ``Tk`` framework (``TkAgg`` backend) does not require any +external dependencies and is normally always available. On certain Linux +distributions, a package named ``python-tk`` (or similar) needs to be +installed. + +Otherwise, the situation (at the time of writing) is as follows: + +============= ========================== ================================= +GUI framework pip-installable? conda or conda-forge-installable? +============= ========================== ================================= +PyQt5 on Python>=3.5 yes +------------- -------------------------- --------------------------------- +PyQt4 PySide: on Windows and OSX yes +------------- -------------------------- --------------------------------- +PyGObject no on Linux +------------- -------------------------- --------------------------------- +PyGTK no no +------------- -------------------------- --------------------------------- +wxPython yes [#]_ yes +============= ========================== ================================= + +.. [#] OSX and Windows wheels available on PyPI. Linux wheels available but + not on PyPI, see https://wxpython.org/pages/downloads/. -GUI Frameworks -============== - -Interactive Matplotlib relies heavily on the interaction with external GUI -frameworks. - -Most GUI frameworks are not pip installable. This makes it tricky to install -them within a virtual environment. This problem does not exist if you use Conda -environments where you can install all Conda supported GUI frameworks directly -into the environment. In regular virtualenv environment various workarounds -exist. Some of these are given here: - -* The ``TKAgg`` backend doesn't require any external dependencies and is - normally always available. -* The ``QT4`` framework ``PySide`` is pip installable. -* ``PYQT5`` is pip installable on Python 3.5. - -Other frameworks are harder to install into a virtual environment. There are at -least two possible ways to get access to these in a virtual environment. - -One often suggested solution is to use the ``--system-site-packages`` option -to virtualenv when creating an environment. This adds all system wide packages -to the virtual environment. However, this breaks the isolation between the -virtual environment and the system install. Among other issues it results in -hard to debug problems with system packages shadowing the environment packages. -If you use `virtualenvwrapper `_ -this can be toggled with the ``toggleglobalsitepackages`` command. - -Alternatively, you can manually symlink the GUI frameworks into the environment. -I.e. to use PyQt5, you should symlink ``PyQt5`` and ``sip`` from your system -site packages directory into the environment taking care that the environment -and the systemwide install use the same python version. +In other cases, you need to install the package in the global (system) +site-packages, and somehow make it available from within the virtual +environment. This can be achieved by any of the following methods (in all +cases, the system-wide Python and the virtualenv Python must be of the same +version): + +- Using ``virtualenv``\'s ``--system-site-packages`` option when creating + an environment adds all system-wide packages to the virtual environment. + However, this breaks the isolation between the virtual environment and the + system install. Among other issues it results in hard to debug problems + with system packages shadowing the environment packages. If you use + `virtualenvwrapper `_, this can be + toggled with the ``toggleglobalsitepackages`` command. + +- `vext `_ allows controlled access + from within the virtualenv to specific system-wide packages without the + overall shadowing issue. A specific package needs to be installed for each + framework, e.g. `vext.pyqt5 `_, etc. + +- The GUI frameworks can be manually symlinked into the environment, e.g. for + PyQt5, you should symlink ``PyQt5`` and ``sip`` from the system site-packages + into the virtualenv site-packages. + +If you are using Matplotlib on OSX, you may also want to consider the +:ref:`OSX framework FAQ `. From 296befbcd601a5089a814c5e9e22c02aca869027 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Wed, 20 Sep 2017 12:45:58 -0700 Subject: [PATCH 2/7] Update installation faq. --- doc/faq/installing_faq.rst | 300 ++++++++++++++----------------------- 1 file changed, 113 insertions(+), 187 deletions(-) diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst index a9ff1b68dd8d..71dfed238787 100644 --- a/doc/faq/installing_faq.rst +++ b/doc/faq/installing_faq.rst @@ -19,18 +19,10 @@ The first thing to try is a :ref:`clean install ` and see if that helps. If not, the best way to test your install is by running a script, rather than working interactively from a python shell or an integrated development environment such as :program:`IDLE` which add additional -complexities. Open up a UNIX shell or a DOS command prompt and cd into a -directory containing a minimal example in a file. Something like -:file:`simple_plot.py` for example:: +complexities. Open up a UNIX shell or a DOS command prompt and run, for +example:: - import matplotlib.pyplot as plt - fig, ax = plt.subplots() - ax.plot([1,2,3]) - plt.show() - -and run it with:: - - python simple_plot.py --verbose-helpful + python -c "from pylab import *; plot(); show()" --verbose-helpful This will give you additional information about which backends matplotlib is loading, version information, and more. At this point you might want to make @@ -42,127 +34,46 @@ If you are still having trouble, see :ref:`reporting-problems`. .. _clean-install: -How to completely remove matplotlib +How to completely remove Matplotlib =================================== -Occasionally, problems with matplotlib can be solved with a clean -installation of the package. - -The process for removing an installation of matplotlib depends on how -matplotlib was originally installed on your system. Follow the steps -below that goes with your original installation method to cleanly -remove matplotlib from your system. - -Source install --------------- - -Unfortunately:: - - python setup.py clean +Occasionally, problems with Matplotlib can be solved with a clean +installation of the package. In order to fully remove an installed Matplotlib: -does not properly clean the build directory, and does nothing to the -install directory. To cleanly rebuild: - -1. Delete the caches from your :ref:`.matplotlib configuration directory +1. Delete the caches from your :ref:`Matplotlib configuration directory `. -2. Delete the ``build`` directory in the source tree. - -3. Delete any matplotlib directories or eggs from your :ref:`installation +2. Delete any Matplotlib directories or eggs from your :ref:`installation directory `. -How to Install -============== - -.. _install-from-git: - -Source install from git ------------------------ - -Clone the main source using one of:: - - git clone git@github.com:matplotlib/matplotlib.git - -or:: - - git clone git://github.com/matplotlib/matplotlib.git - -and build and install as usual with:: - - > cd matplotlib - > python setup.py install - -.. note:: - - If you are on debian/ubuntu, you can get all the dependencies - 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:: - - su -c "yum-builddep python-matplotlib" - - This does not build matplotlib, but it does get all of the - build dependencies, which will make building from source easier. - - -If you want to be able to follow the development branch as it changes -just replace the last step with (make sure you have **setuptools** -installed):: - - > python setup.py develop - -This creates links in the right places and installs the command -line script to the appropriate places. - -.. note:: - Mac OSX users please see the :ref:`build_osx` guide. - - Windows users please see the :ref:`build_windows` guide. - -Then, if you want to update your matplotlib at any time, just do:: - - > git pull - -When you run `git pull`, if the output shows that only Python files have been -updated, you are all set. If C files have changed, you need to run the `python -setup.py develop` command again to compile them. - -There is more information on :ref:`using git ` in -the developer docs. - - Linux Notes =========== -Because most Linux distributions use some sort of package manager, -we do not provide a pre-built binary for the Linux platform. -Instead, we recommend that you use the "Add Software" method for -your system to install matplotlib. This will guarantee that everything -that is needed for matplotlib will be installed as well. +We recommend that you use your distribution's package manager to install +Matplotlib. This will guarantee that Matplotlib's dependencies will be +installed as well. + +If, for some reason, you can not use the package manager, you may use the +manylinux wheels available on PyPI:: -If, for some reason, you can not use the package manager, Linux usually -comes with at least a basic build system. Follow the :ref:`instructions -` found above for how to build and install matplotlib. + python -mpip install matplotlib +or :ref:`build Matplotlib from source `. -OS-X Notes -========== +OSX Notes +========= .. _which-python-for-osx: -Which python for OS X? ----------------------- +Which python for OSX? +--------------------- -Apple ships OS X with its own Python, in ``/usr/bin/python``, and its own copy -of matplotlib. Unfortunately, the way Apple currently installs its own copies -of numpy, scipy and matplotlib means that these packages are difficult to +Apple ships OSX with its own Python, in ``/usr/bin/python``, and its own copy +of Matplotlib. Unfortunately, the way Apple currently installs its own copies +of NumPy, Scipy and Matplotlib means that these packages are difficult to upgrade (see `system python packages`_). For that reason we strongly suggest that you install a fresh version of Python and use that as the basis for -installing libraries such as numpy and matplotlib. One convenient way to +installing libraries such as NumPy and Matplotlib. One convenient way to install matplotlib with other useful Python software is to use one of the excellent Python scientific software collections that are now available: @@ -198,7 +109,7 @@ Installing OSX binary wheels ---------------------------- If you are using recent Python from https://www.python.org, Macports or -Homebrew, then you can use the standard pip installer to install matplotlib +Homebrew, then you can use the standard pip installer to install Matplotlib binaries in the form of wheels. Python.org Python @@ -208,54 +119,53 @@ Install pip following the `standard pip install instructions `_. For the impatient, open a new Terminal.app window and:: - curl -O https://bootstrap.pypa.io/get-pip.py + curl -O https://bootstrap.pypa.io/get-pip.py -Then (Python 2.7):: +Then (Python 2):: - python get-pip.py + python get-pip.py or (Python 3):: - python3 get-pip.py + python3 get-pip.py -You can now install matplotlib and all its dependencies with:: +You can now install matplotlib and all its dependencies with :: - pip install matplotlib + python -mpip install matplotlib + +or :: + + python3 -mpip install matplotlib Macports Python ^^^^^^^^^^^^^^^ For Python 2.7:: - sudo port install py27-pip - sudo pip-2.7 install matplotlib + sudo port install py27-pip + sudo python2.7 -mpip install matplotlib For Python 3.4:: - sudo port install py34-pip - sudo pip-3.4 install matplotlib + sudo port install py34-pip + sudo python3.4 -mpip install matplotlib Homebrew Python ^^^^^^^^^^^^^^^ -For Python 2.7:: - - pip2 install matplotlib +For Python 2:: -For Python 3.4:: + python2 -mpip install matplotlib - pip3 install matplotlib +For Python 3:: -You might also want to install IPython; we recommend you install IPython with -the IPython notebook option, like this: + python3 -mpip install matplotlib -* Python.org Python: ``pip install ipython[notebook]`` -* Macports ``sudo pip-2.7 install ipython[notebook]`` or ``sudo pip-3.4 - install ipython[notebook]`` -* Homebrew ``pip2 install ipython[notebook]`` or ``pip3 install - ipython[notebook]`` +You might also want to install IPython or the Jupyter notebook (``pythonX -mpip +install ipython``, ``pythonX -mpip install notebook``, where ``pythonX`` is set +as above). -Pip problems +pip problems ^^^^^^^^^^^^ If you get errors with pip trying to run a compiler like ``gcc`` or ``clang``, @@ -264,56 +174,15 @@ then the first thing to try is to `install xcode retry the install. If that does not work, then check :ref:`reporting-problems`. -Installing via OSX mpkg installer package ------------------------------------------ - -matplotlib also has a disk image (``.dmg``) installer, which contains a -typical Installer.app package to install matplotlib. You should use binary -wheels instead of the disk image installer if you can, because: - -* wheels work with Python.org Python, homebrew and macports, the disk image - installer only works with Python.org Python. -* The disk image installer doesn't check for recent versions of packages that - matplotlib depends on, and unconditionally installs the versions of - dependencies contained in the disk image installer. This can overwrite - packages that you have already installed, which might cause problems for - other packages, if you have a pre-existing Python.org setup on your - computer. - -If you still want to use the disk image installer, read on. - -.. note:: - Before installing via the disk image installer, be sure that all of the - packages were compiled for the same version of python. Often, the download - site for NumPy and matplotlib will display a supposed 'current' version of - the package, but you may need to choose a different package from the full - list that was built for your combination of python and OSX. - -The disk image installer will have a ``.dmg`` extension, and will have a name -like :file:`matplotlib-1.4.0-py2.7-macosx10.6.dmg`. -The name of the installer depends on the versions of python and matplotlib it -was built for, and the version of OSX that the matching Python.org installer -was built for. For example, if the mathing Python.org Python installer was -built for OSX 10.6 or greater, the dmg file will end in ``-macosx10.6.dmg``. -You need to download this disk image file, open the disk image file by double -clicking, and find the new matplotlib disk image icon on your desktop. Double -click on that icon to show the contents of the image. Then double-click on -the ``.mpkg`` icon, which will have a name like -:file:`matplotlib-1.4.0-py2.7-macosx10.6.mpkg`, it will run the Installer.app, -prompt you for a password if you need system-wide installation privileges, and -install to a directory like -:file:`/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages` -(exact path depends on your Python version). - Checking your installation -------------------------- -The new version of matplotlib should now be on your Python "path". Check this +The new version of Matplotlib should now be on your Python "path". Check this with one of these commands at the Terminal.app command line:: python2.7 -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__' -(Python 2.7) or:: +(Python 2) or:: python3.4 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)' @@ -321,7 +190,7 @@ with one of these commands at the Terminal.app command line:: 1.4.0 /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/matplotlib/__init__.pyc -where ``1.4.0`` is the matplotlib version you just installed, and the path +where ``1.4.0`` is the Matplotlib version you just installed, and the path following depends on whether you are using Python.org Python, Homebrew or Macports. If you see another version, or you get an error like this:: @@ -340,14 +209,71 @@ or:: If you get the result ``/usr/bin/python2.7``, then you are getting the Python installed with OSX, which is probably not what you want. Try closing and -restarting Terminal.app before running the check again. If that doesn't fix -the problem, depending on which Python you wanted to use, consider -reinstalling Python.org Python, or check your homebrew or macports setup. -Remember that the disk image installer only works for Python.org Python, and -will not get picked up by other Pythons. If all these fail, please let us -know: see :ref:`reporting-problems`. +restarting Terminal.app before running the check again. If that doesn't fix the +problem, depending on which Python you wanted to use, consider reinstalling +Python.org Python, or check your homebrew or macports setup. Remember that +the disk image installer only works for Python.org Python, and will not get +picked up by other Pythons. If all these fail, please :ref:`let us know +`. Windows Notes ============= See :ref:`installing_windows`. + +.. _install-from-git: + +Install from source +=================== + +Clone the main source using one of:: + + git clone git@github.com:matplotlib/matplotlib.git + +or:: + + git clone git://github.com/matplotlib/matplotlib.git + +and build and install as usual with:: + + cd matplotlib + python -mpip install . + +.. note:: + + If you are on Debian/Ubuntu, you can get all the dependencies 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:: + + su -c 'yum-builddep python-matplotlib' + + This does not build Matplotlib, but it does get all of the build + dependencies, which will make building from source easier. + +If you want to be able to follow the development branch as it changes +just replace the last step with:: + + python -mpip install -e . + +This creates links and installs the command line script in the appropriate +places. + +.. note:: + OSX users please see the :ref:`build_osx` guide. + + Windows users please see the :ref:`build_windows` guide. + +Then, if you want to update your matplotlib at any time, just do:: + + git pull + +When you run ``git pull``, if the output shows that only Python files have +been updated, you are all set. If C files have changed, you need to run ``pip +install -e .`` again to compile them. + +There is more information on :ref:`using git ` in the developer +docs. From 10f78c474b29df9dff905e3204566c9e275988bd Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Wed, 20 Sep 2017 13:22:04 -0700 Subject: [PATCH 3/7] Update troubleshooting faq. Mainly dedent the bullet list, so that it does not appear as a rst blockquote. --- doc/faq/troubleshooting_faq.rst | 86 +++++++++++++++------------------ 1 file changed, 39 insertions(+), 47 deletions(-) diff --git a/doc/faq/troubleshooting_faq.rst b/doc/faq/troubleshooting_faq.rst index fe438bd1c69a..c6f3c7d4d806 100644 --- a/doc/faq/troubleshooting_faq.rst +++ b/doc/faq/troubleshooting_faq.rst @@ -82,63 +82,57 @@ Getting help There are a number of good resources for getting help with matplotlib. There is a good chance your question has already been asked: - - The `mailing list archive `_. +- The `mailing list archive `_. - - `Github issues `_. +- `Github issues `_. - - Stackoverflow questions tagged `matplotlib - `_. +- Stackoverflow questions tagged `matplotlib + `_. -If you are unable to find an answer to your question through search, -please provide the following information in your e-mail to the -`mailing list +If you are unable to find an answer to your question through search, please +provide the following information in your e-mail to the `mailing list `_: - * your operating system; (Linux/UNIX users: post the output of ``uname -a``) +* Your operating system (Linux/UNIX users: post the output of ``uname -a``). - * matplotlib version:: +* Matplotlib version:: - python -c `import matplotlib; print matplotlib.__version__` + python -c "import matplotlib; print matplotlib.__version__" - * where you obtained matplotlib (e.g., your Linux distribution's - packages, github, PyPi, or Anaconda_ or `Enthought Canopy - `_). +* Where you obtained Matplotlib (e.g., your Linux distribution's packages, + Github, PyPi, or `Anaconda `_ or + `Enthought Canopy `_). -.. _Anaconda: https://www.continuum.io/downloads +* Any customizations to your ``matplotlibrc`` file (see + :ref:`sphx_glr_tutorials_introductory_customizing.py`). +* If the problem is reproducible, please try to provide a *minimal*, standalone + Python script that demonstrates the problem. This is *the* critical step. + If you can't post a piece of code that we can run and reproduce your error, + the chances of getting help are significantly diminished. Very often, the + mere act of trying to minimize your code to the smallest bit that produces + the error will help you find a bug in *your* code that is causing the + problem. - * any customizations to your ``matplotlibrc`` file (see - :ref:`sphx_glr_tutorials_introductory_customizing.py`). +* You can get very helpful debugging output from matlotlib by running your + script with a ``verbose-helpful`` or ``--verbose-debug`` flags and posting + the verbose output the lists:: - * if the problem is reproducible, please try to provide a *minimal*, - standalone Python script that demonstrates the problem. This is - *the* critical step. If you can't post a piece of code that we - can run and reproduce your error, the chances of getting help are - significantly diminished. Very often, the mere act of trying to - minimize your code to the smallest bit that produces the error - will help you find a bug in *your* code that is causing the - problem. + python simple_plot.py --verbose-helpful > output.txt - * you can get very helpful debugging output from matlotlib by - running your script with a ``verbose-helpful`` or - ``--verbose-debug`` flags and posting the verbose output the - lists:: +If you compiled Matplotlib yourself, please also provide: - > python simple_plot.py --verbose-helpful > output.txt +* any changes you have made to ``setup.py`` or ``setupext.py``. +* the output of:: -If you compiled matplotlib yourself, please also provide + rm -rf build + python setup.py build - * any changes you have made to ``setup.py`` or ``setupext.py`` - * the output of:: + The beginning of the build output contains lots of details about your + platform that are useful for the Matplotlib developers to diagnose your + problem. - rm -rf build - python setup.py build - - The beginning of the build output contains lots of details about your - platform that are useful for the matplotlib developers to diagnose - your problem. - - * your compiler version -- e.g., ``gcc --version`` +* your compiler version -- e.g., ``gcc --version``. Including this information in your first e-mail to the mailing list will save a lot of time. @@ -149,24 +143,22 @@ tracker only periodically. If your problem has been determined to be a bug and can not be quickly solved, you may be asked to file a bug in the tracker so the issue doesn't get lost. - .. _git-trouble: Problems with recent git versions ================================= -First make sure you have a clean build and install (see -:ref:`clean-install`), get the latest git update, install it and run a -simple test script in debug mode:: +First make sure you have a clean build and install (see :ref:`clean-install`), +get the latest git update, install it and run a simple test script in debug +mode:: - rm -rf build rm -rf /path/to/site-packages/matplotlib* + git clean -xdf git pull python setup.py install > build.out python examples/pylab_examples/simple_plot.py --verbose-debug > run.out -and post :file:`build.out` and :file:`run.out` to the -`matplotlib-devel +and post :file:`build.out` and :file:`run.out` to the `matplotlib-devel `_ mailing list (please do not post git problems to the `users list `_). From ca0114fdba5e1a2ec3a979acd748a07e88fb5d63 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Wed, 20 Sep 2017 22:25:32 -0700 Subject: [PATCH 4/7] Fully switch from setup.py install to pip. --- INSTALL.rst | 22 ++++++++++------------ doc/devel/contributing.rst | 20 +++++++++----------- doc/faq/troubleshooting_faq.rst | 2 +- 3 files changed, 20 insertions(+), 24 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index 3e5d1dde0dc8..354a34eb89c5 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -22,8 +22,8 @@ Installing an official release Matplotlib and most of its dependencies are all available as wheel packages for macOS, Windows and Linux distributions:: - python -m pip install -U pip - python -m pip install -U matplotlib + python -mpip install -U pip + python -mpip install -U matplotlib .. note:: @@ -150,16 +150,14 @@ Python, NumPy, libpng and FreeType), you can build Matplotlib. :: cd matplotlib - python setup.py build - python setup.py install + python -mpip install . -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 -installed, and so on. This file will be particularly useful to those -packaging Matplotlib. +We provide a setup.cfg_ file 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 installed, and so on. This +file will be particularly useful to those packaging Matplotlib. + +.. _setup.cfg: https://raw.githubusercontent.com/matplotlib/matplotlib/master/setup.cfg.template If you have installed prerequisites to nonstandard places and need to inform Matplotlib where they are, edit ``setupext.py`` and add the base @@ -282,7 +280,7 @@ If you are using MacPorts, execute the following instead:: After installing the above requirements, install Matplotlib from source by executing:: - python setup.py install + python -mpip install . Note that your environment is somewhat important. Some conda users have found that, to run the tests, their PYTHONPATH must include diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index f29f624aa0fd..eb682e3bae41 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -90,33 +90,32 @@ the env ``MPLLOCALFREETYPE`` as:: export MPLLOCALFREETYPE=1 -or copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit it to contain :: +or copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit it to contain +:: [test] local_freetype = True - To install Matplotlib (and compile the c-extensions) run the following command from the top-level directory :: - pip install -v -e ./ + python -mpip install -ve . This installs Matplotlib in 'editable/develop mode', i.e., builds everything and places the correct link entries in the install directory so that python will be able to import Matplotlib from the source directory. Thus, any changes to the ``*.py`` files will be reflected the next time you import the library. If you change the -c-extension source (which might happen if you change branches) you -will need to run:: +C-extension source (which might happen if you change branches) you +will need to run :: python setup.py build -or re-run ``pip install -v -e ./``. - +or re-run ``python -mpip install -ve .``. Alternatively, if you do :: - pip install -v ./ + python -mpip install -v . all of the files will be copied to the installation directory however, you will have to rerun this command every time the source is changed. @@ -132,7 +131,6 @@ environment is set up properly:: python tests.py - .. _pytest: http://doc.pytest.org/en/latest/ .. _pep8: https://pep8.readthedocs.io/en/latest/ .. _mock: https://docs.python.org/dev/library/unittest.mock.html @@ -254,12 +252,12 @@ tools: * Code with a good unittest coverage (at least 70%, better 100%), check with:: - pip install coverage + python -mpip install coverage python tests.py --with-coverage * No pyflakes warnings, check with:: - pip install pyflakes + python -mpip install pyflakes pyflakes path/to/module.py .. note:: diff --git a/doc/faq/troubleshooting_faq.rst b/doc/faq/troubleshooting_faq.rst index c6f3c7d4d806..7074147c142b 100644 --- a/doc/faq/troubleshooting_faq.rst +++ b/doc/faq/troubleshooting_faq.rst @@ -155,7 +155,7 @@ mode:: rm -rf /path/to/site-packages/matplotlib* git clean -xdf git pull - python setup.py install > build.out + python -mpip install -v . > build.out python examples/pylab_examples/simple_plot.py --verbose-debug > run.out and post :file:`build.out` and :file:`run.out` to the `matplotlib-devel From 87960f855a8413beef6dabdbd9defbd8969cd634 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Fri, 6 Oct 2017 21:46:33 -0400 Subject: [PATCH 5/7] DOC: tweak package manager istall wording --- doc/faq/installing_faq.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst index 71dfed238787..6bb58fb20a4e 100644 --- a/doc/faq/installing_faq.rst +++ b/doc/faq/installing_faq.rst @@ -49,9 +49,9 @@ installation of the package. In order to fully remove an installed Matplotlib: Linux Notes =========== -We recommend that you use your distribution's package manager to install -Matplotlib. This will guarantee that Matplotlib's dependencies will be -installed as well. +To install Matplotlib at the system-level we recommend that you use your +distribution's package manager to install Matplotlib. This will guarantee +that Matplotlib's dependencies will be installed as well. If, for some reason, you can not use the package manager, you may use the manylinux wheels available on PyPI:: From 3ae1336abb6cac295692ef01247a03964ab7b4f7 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Fri, 6 Oct 2017 21:54:36 -0400 Subject: [PATCH 6/7] DOC: tweak OSX install faq Mostly moving away from python3.4 in the examples. --- doc/faq/installing_faq.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst index 6bb58fb20a4e..7edd65628c80 100644 --- a/doc/faq/installing_faq.rst +++ b/doc/faq/installing_faq.rst @@ -140,15 +140,15 @@ or :: Macports Python ^^^^^^^^^^^^^^^ -For Python 2.7:: +For Python 2:: sudo port install py27-pip - sudo python2.7 -mpip install matplotlib + sudo python2 -mpip install matplotlib -For Python 3.4:: +For Python 3:: - sudo port install py34-pip - sudo python3.4 -mpip install matplotlib + sudo port install py36-pip + sudo python3.6 -mpip install matplotlib Homebrew Python ^^^^^^^^^^^^^^^ @@ -180,17 +180,17 @@ Checking your installation The new version of Matplotlib should now be on your Python "path". Check this with one of these commands at the Terminal.app command line:: - python2.7 -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__' + python2 -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__' (Python 2) or:: - python3.4 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)' + python3 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)' -(Python 3.4). You should see something like this:: +(Python 3). You should see something like this:: - 1.4.0 /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/matplotlib/__init__.pyc + 2.1.0 /Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/matplotlib/__init__.pyc -where ``1.4.0`` is the Matplotlib version you just installed, and the path +where ``2.1.0`` is the Matplotlib version you just installed, and the path following depends on whether you are using Python.org Python, Homebrew or Macports. If you see another version, or you get an error like this:: @@ -201,11 +201,11 @@ Macports. If you see another version, or you get an error like this:: then check that the Python binary is the one you expected by doing one of these commands in Terminal.app:: - which python2.7 + which python2 or:: - which python3.4 + which python3 If you get the result ``/usr/bin/python2.7``, then you are getting the Python installed with OSX, which is probably not what you want. Try closing and From 5562bf03808e1699f11ee55243fce0934f33c4e4 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Fri, 6 Oct 2017 23:36:06 -0700 Subject: [PATCH 7/7] Tweak wording in install faq. --- doc/faq/installing_faq.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst index 7edd65628c80..8dcb047da395 100644 --- a/doc/faq/installing_faq.rst +++ b/doc/faq/installing_faq.rst @@ -49,12 +49,12 @@ installation of the package. In order to fully remove an installed Matplotlib: Linux Notes =========== -To install Matplotlib at the system-level we recommend that you use your -distribution's package manager to install Matplotlib. This will guarantee -that Matplotlib's dependencies will be installed as well. +To install Matplotlib at the system-level, we recommend that you use your +distribution's package manager. This will guarantee that Matplotlib's +dependencies will be installed as well. -If, for some reason, you can not use the package manager, you may use the -manylinux wheels available on PyPI:: +If, for some reason, you cannot use the package manager, you may use the wheels +available on PyPI:: python -mpip install matplotlib