matplotlib
diff --git a/‎doc/devel/contributing.rst
Lines changed: 46 additions & 40 deletions b/‎doc/devel/contributing.rst
Lines changed: 46 additions & 40 deletions
@@ -21,44 +21,62 @@ also welcome to post feature requests or pull requests.
 Retrieving and installing the latest version of the code
 ========================================================
 
+When working on the Matplotlib source, setting up a `virtual
+environment
+<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ or a
+`conda environment <http://conda.pydata.org/docs/using/envs.html>`_ is
+recommended.
+
+.. warning::
+
+   If you already have a version of matplotlib installed, you will need to
+   uninstall it.
 
 We use `Git <https://git-scm.com/>`_ for version control and
 `GitHub <https://github.com/>`_ for hosting our main repository.
 
-You can check out the latest sources with the command::
+You can check out the latest sources with the command (see
+:ref:`set-up-fork` for more details)::
 
     git clone git@github.com:matplotlib/matplotlib.git
 
+and navigate to the matplotlib directory.
 
-After obtaining a local copy of the matplotlib source code (:ref:`set-up-fork`),
-navigate to the matplotlib directory and run the following in the shell::
-    
-    python setup.py develop
+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::
 
-or::
-  
-   pip install -v -e .
+  export MPLLOCALFREETYPE=1
 
+or copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit to contain ::
 
-This installs matplotlib for development (i.e., builds everything and places the
-symbolic links back to the source code).
+  [test]
+  local_freetype = True
 
-.. warning::
 
-   If you already have a version of matplotlib installed, you will need to
-   uninstall it.
+To install Matplotlib (and compile the c-extensions) run the following
+command from the top-level directory ::
 
+    pip install -v -e ./
 
-.. note::
-  
-    If you decide to do install with ``python setup.py develop`` or ``pip
-    install -v -e``, you will have to rerun::
-   
-      python setup.py build
+This installs Matplotlib in 'editable/develop mode', i.e.,
+builds everything and places symbolic links back to the source code
+from the install 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::
+
+   python setup.py build
+
+or re-run ``pip install -v -e ./``.
 
-    every time the source code of a compiled extension is changed (for
-    instance when switching branches or pulling changes from upstream).
 
+Alternatively, if you do ::
+
+  pip 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.
 
 
 You can then run the tests to check your work environment is set up properly::
@@ -70,25 +88,13 @@ You can then run the tests to check your work environment is set up properly::
 .. _pep8: https://pep8.readthedocs.io/en/latest/
 
 .. note::
-    
+
   **Additional dependencies for testing**: nose_ (version 1.0 or later), `mock
   <https://docs.python.org/dev/library/unittest.mock.html>`_ (if python < 3.3), `Ghostscript
   <http://www.ghostscript.com/>`_, `Inkscape <http://inkscape.org>`_
 
-.. note:: To make sure the tests run locally:
-
-      * Copy setup.cfg.template to setup.cfg
-      * Edit setup.cfg to set ``test`` to True, and ``local_freetype`` to True
-      * If you have built matplotlib previously, remove the ``build`` folder.
-      * Execute the build command.
-
-When working on bleeding edge packages, setting up a
-`virtual environment
-<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ or a `conda
-environment <http://conda.pydata.org/docs/using/envs.html>`_ is recommended.
-
 .. seealso::
-  
+
   * :ref:`testing`
 
 
@@ -137,7 +143,7 @@ You may want to consider sending an email to the mailing list for more
 visibility.
 
 .. seealso::
-   
+
   * `Git documentation <https://git-scm.com/documentation>`_
   * :ref:`development-workflow`.
   * :ref:`using-git`
@@ -196,12 +202,12 @@ tools:
 
     * Code with a good unittest coverage (at least 70%, better 100%), check
       with::
-      
+
         pip install coverage
         python tests.py --with-coverage
 
     * No pyflakes warnings, check with::
-      
+
         pip install pyflakes
         pyflakes path/to/module.py
 
@@ -227,10 +233,10 @@ Issues for New Contributors
 ---------------------------
 
 New contributors should look for the following tags when looking for issues.
-We strongly recommend that new contributors tackle 
+We strongly recommend that new contributors tackle
 `new-contributor-friendly <https://github.com/matplotlib/matplotlib/labels/new-contributor-friendly>`_
 issues (easy, well documented issues, that do not require an understanding of
-the different submodules of matplotlib) and 
+the different submodules of matplotlib) and
 `Easy-fix <https://github.com/matplotlib/matplotlib/labels/Difficulty%3A%20Easy>`_
 issues. This helps the contributor become familiar with the contribution
 workflow, and for the core devs to become acquainted with the contributor;