Merge pull request #8888 from roopchansinghv/scipy2017SprintVR

DOC: Dev installation instructions documentation issue

1 files changed, 20 insertions, 9 deletions

diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
index c9670eff3..c3e8cdf84 100644
--- a/doc/devel/contributing.rst
+++ b/doc/devel/contributing.rst
@@ -48,18 +48,28 @@ Thank you for your help in keeping bug reports complete, targeted and descriptiv
 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.
+When developing Matplotlib, sources must be downloaded, built, and installed into
+a local environment on your machine.
+
+Follow the instructions detailed :ref:`here <install_from_source>` to set up your
+environment to build Matplotlib from source.
 
 .. warning::
 
-   If you already have a version of Matplotlib installed, use an
-   virtual environment or uninstall using the same method you used
-   to install it.  Installing multiple versions of Matplotlib via different
-   methods into the same environment may not always work as expected.
+   When working on Matplotlib sources, having multiple versions installed by
+   different methods into the same environment may not always work as expected.
+
+To work on Matplotlib sources, it is strongly recommended to set up an alternative
+development environment, using the something like `virtual environments in python
+<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_, or a
+`conda environment <http://conda.pydata.org/docs/using/envs.html>`_.
+
+If you choose to use an already existing environment, and not a clean virtual or
+conda environment, uninstall the current version of Matplotlib in that enviroment
+using the same method used to install it.
+
+If working on Matplotlib documentation only, the above steps are *not* absolutely
+necessary.
 
 We use `Git <https://git-scm.com/>`_ for version control and
 `GitHub <https://github.com/>`_ for hosting our main repository.
@@ -73,6 +83,7 @@ and navigate to the :file:`matplotlib` directory. If you have the proper privile
 you can use ``git@`` instead of  ``https://``, which works through the ssh protocol 
 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::