fixes from reviewers, failed CI, reshuffle FreeType section

mattip · mattip · commit 753bed29718f · 2017-10-16T15:46:35.000+03:00
diff --git 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
@@ -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
@@ -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))
