From 02b434e4344549f8c8c98f5714e6546274cb8d1d Mon Sep 17 00:00:00 2001 From: David Stansby Date: Wed, 18 Oct 2017 11:56:22 +0100 Subject: [PATCH] Backport PR #9378: DOC: fill out dev docs --- doc/devel/contributing.rst | 25 +++++++++++++++++++------ doc/devel/testing.rst | 31 +++++++------------------------ setupext.py | 5 ++++- 3 files changed, 30 insertions(+), 31 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index eb682e3bae41..d5d288af5a97 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. + + +Installing 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 7b71b22d7982..d5ed965cc7d5 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -20,6 +20,10 @@ infrastructure are in :mod:`matplotlib.testing`. Requirements ------------ +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: - pytest_, version 3.0.0 or later @@ -35,26 +39,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 ----------------- @@ -164,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 @@ -262,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 diff --git a/setupext.py b/setupext.py index 997b3ea5ba5b..fa685c7e172d 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: