From 60e9feba01383d77135adaa49f670d8b6d1487df Mon Sep 17 00:00:00 2001 From: mattip Date: Thu, 12 Oct 2017 14:43:07 +0300 Subject: [PATCH 1/6] fill out dev docs --- doc/devel/testing.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index 7b71b22d7982..49f2f72f5a66 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -8,6 +8,7 @@ Matplotlib's testing infrastructure depends on pytest_. The tests are in :file:`lib/matplotlib/tests`, and customizations to the pytest testing infrastructure are in :mod:`matplotlib.testing`. +.. _dependencies: http://matplotlib.org/users/installing.html#dependencies .. _pytest: http://doc.pytest.org/en/latest/ .. _mock: https://docs.python.org/3/library/unittest.mock.html> .. _Ghostscript: https://www.ghostscript.com/ @@ -20,6 +21,13 @@ infrastructure are in :mod:`matplotlib.testing`. Requirements ------------ +We strongly recommend developing new features in a seperate virtualenv. + +Install all the matplotlib dependencies_, and install matplotlib into the +virtualenv with ``pip install -e matplotlib`` (but note the changes needed to +``setup.cfg`` below) which will allow you to edit the code without +reinstalling. + The following software is required to run the tests: - pytest_, version 3.0.0 or later From 1bf44509dbc306c22b5516d150fa6013314a6aea Mon Sep 17 00:00:00 2001 From: mattip Date: Fri, 13 Oct 2017 02:55:36 +0300 Subject: [PATCH 2/6] document alternative to automatic download --- doc/devel/testing.rst | 2 +- setupext.py | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index 49f2f72f5a66..3a5a635fab2c 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -23,7 +23,7 @@ Requirements We strongly recommend developing new features in a seperate virtualenv. -Install all the matplotlib dependencies_, and install matplotlib into the +Install all the Matplotlib dependencies_, and install matplotlib into the virtualenv with ``pip install -e matplotlib`` (but note the changes needed to ``setup.cfg`` below) which will allow you to edit the code without reinstalling. diff --git a/setupext.py b/setupext.py index 997b3ea5ba5b..de4cd0ca784c 100644 --- a/setupext.py +++ b/setupext.py @@ -1187,7 +1187,10 @@ def do_custom_build(self): else: break else: - raise IOError("Failed to download freetype") + raise IOError("Failed to download freetype. " + "You can download the file by " + "alternative means and copy it " + " to '{0}'".format(tarball_path)) try: os.makedirs(tarball_cache_dir) except OSError: From 753bed29718fa00ac150768c1608a98dcc0da648 Mon Sep 17 00:00:00 2001 From: mattip Date: Mon, 16 Oct 2017 15:46:35 +0300 Subject: [PATCH 3/6] fixes from reviewers, failed CI, reshuffle FreeType section --- doc/devel/contributing.rst | 25 +++++++++++++++++++------ doc/devel/testing.rst | 29 +++-------------------------- setupext.py | 2 +- 3 files changed, 23 insertions(+), 33 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index eb682e3bae41..92173f0e6c6d 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -45,6 +45,8 @@ use to organize this information. Thank you for your help in keeping bug reports complete, targeted and descriptive. +.. _installing_for_devs: + Retrieving and installing the latest version of the code ======================================================== @@ -84,17 +86,28 @@ you can use ``git@`` instead of ``https://``, which works through the ssh proto and might be easier to use if you are using 2-factor authentication. -To make sure the tests run locally you must build against the correct version -of freetype. To configure the build system to fetch and build it either export -the env ``MPLLOCALFREETYPE`` as:: +Building matplotlib for image comparison tests +---------------------------------------------- - export MPLLOCALFREETYPE=1 +Matplotlib's test suite makes heavy use of image comparison tests, +meaning the result of a plot is compared against a known good result. +Unfortunately, different versions of FreeType produce differently +formed characters, causing these image comparisons to fail. To make +them reproducible, matplotlib can be built with a special local copy +of FreeType. This is recommended for all matplotlib developers. -or copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit it to contain -:: +Copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit it to contain:: [test] local_freetype = True + tests = True + +or set the ``MPLLOCALFREETYPE`` environmental variable to any true +value. + + +Install matplotlib in developer mode +------------------------------------ To install Matplotlib (and compile the c-extensions) run the following command from the top-level directory :: diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index 3a5a635fab2c..77400453fe28 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -21,12 +21,9 @@ infrastructure are in :mod:`matplotlib.testing`. Requirements ------------ -We strongly recommend developing new features in a seperate virtualenv. - -Install all the Matplotlib dependencies_, and install matplotlib into the -virtualenv with ``pip install -e matplotlib`` (but note the changes needed to -``setup.cfg`` below) which will allow you to edit the code without -reinstalling. +Install the latest version of Matplotlib as documented in +:ref:`installing_for_devs` In particular, follow the instructions to use a +local FreeType build The following software is required to run the tests: @@ -43,26 +40,6 @@ Optionally you can install: - pytest-xdist_ to run tests in parallel -Building matplotlib for image comparison tests ----------------------------------------------- - -matplotlib's test suite makes heavy use of image comparison tests, -meaning the result of a plot is compared against a known good result. -Unfortunately, different versions of FreeType produce differently -formed characters, causing these image comparisons to fail. To make -them reproducible, matplotlib can be built with a special local copy -of FreeType. This is recommended for all matplotlib developers. - -Add the following content to a ``setup.cfg`` file at the root of the -matplotlib source directory:: - - [test] - local_freetype = True - tests = True - -or by setting the ``MPLLOCALFREETYPE`` environmental variable to any true -value. - Running the tests ----------------- diff --git a/setupext.py b/setupext.py index de4cd0ca784c..fa685c7e172d 100644 --- a/setupext.py +++ b/setupext.py @@ -1187,7 +1187,7 @@ def do_custom_build(self): else: break else: - raise IOError("Failed to download freetype. " + raise IOError("Failed to download freetype. " "You can download the file by " "alternative means and copy it " " to '{0}'".format(tarball_path)) From df0cdd0e43ae2a3f906c1b7dcf1f772210ab852d Mon Sep 17 00:00:00 2001 From: mattip Date: Mon, 16 Oct 2017 23:12:37 +0300 Subject: [PATCH 4/6] remove unneeded link --- doc/devel/testing.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index 77400453fe28..cd760d9c3737 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -8,7 +8,6 @@ Matplotlib's testing infrastructure depends on pytest_. The tests are in :file:`lib/matplotlib/tests`, and customizations to the pytest testing infrastructure are in :mod:`matplotlib.testing`. -.. _dependencies: http://matplotlib.org/users/installing.html#dependencies .. _pytest: http://doc.pytest.org/en/latest/ .. _mock: https://docs.python.org/3/library/unittest.mock.html> .. _Ghostscript: https://www.ghostscript.com/ From 680f1786394908a8f4f5b2caed355cadb30ed61f Mon Sep 17 00:00:00 2001 From: mattip Date: Tue, 17 Oct 2017 18:13:10 +0300 Subject: [PATCH 5/6] matplotlib to Matplotlib --- doc/devel/contributing.rst | 8 ++++---- doc/devel/testing.rst | 7 +++---- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 92173f0e6c6d..93f2328dbf4a 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -86,15 +86,15 @@ you can use ``git@`` instead of ``https://``, which works through the ssh proto and might be easier to use if you are using 2-factor authentication. -Building matplotlib for image comparison tests +Building Matplotlib for image comparison tests ---------------------------------------------- Matplotlib's test suite makes heavy use of image comparison tests, meaning the result of a plot is compared against a known good result. Unfortunately, different versions of FreeType produce differently formed characters, causing these image comparisons to fail. To make -them reproducible, matplotlib can be built with a special local copy -of FreeType. This is recommended for all matplotlib developers. +them reproducible, Matplotlib can be built with a special local copy +of FreeType. This is recommended for all Matplotlib developers. Copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit it to contain:: @@ -106,7 +106,7 @@ or set the ``MPLLOCALFREETYPE`` environmental variable to any true value. -Install matplotlib in developer mode +Install Matplotlib in developer mode ------------------------------------ To install Matplotlib (and compile the c-extensions) run the following diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index cd760d9c3737..d5ed965cc7d5 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -148,8 +148,7 @@ Writing an image based test is only slightly more difficult than a simple test. The main consideration is that you must specify the "baseline", or expected, images in the :func:`~matplotlib.testing.decorators.image_comparison` decorator. For -example, this test generates a single image and automatically tests -it:: +example, this test generates a single image and automatically tests it:: import numpy as np import matplotlib @@ -246,13 +245,13 @@ repository `_ -- for example, see `its Travis page `_. -If you want to enable Travis CI for your personal matplotlib GitHub +If you want to enable Travis CI for your personal Matplotlib GitHub repo, simply enable the repo to use Travis CI in either the Travis CI UI or the GitHub UI (Admin | Service Hooks). For details, see `the Travis CI Getting Started page `_. This generally isn't necessary, since any pull request submitted against -the main matplotlib repository will be tested. +the main Matplotlib repository will be tested. Once this is configured, you can see the Travis CI results at https://travis-ci.org/your_GitHub_user_name/matplotlib -- here's `an From c856d0c6483074ef0ff0882610af7e2a0f4cc0a0 Mon Sep 17 00:00:00 2001 From: mattip Date: Tue, 17 Oct 2017 20:56:38 +0300 Subject: [PATCH 6/6] add ..ing --- doc/devel/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 93f2328dbf4a..d5d288af5a97 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -106,8 +106,8 @@ or set the ``MPLLOCALFREETYPE`` environmental variable to any true value. -Install Matplotlib in developer mode ------------------------------------- +Installing Matplotlib in developer mode +--------------------------------------- To install Matplotlib (and compile the c-extensions) run the following command from the top-level directory ::