Merge pull request #15617 from pambot/macosx-dev-docs-update

tacaswell · web-flow · commit 3f4d4c719b0b · 2020-07-02T21:37:30.000-04:00
DOC: Update dev-install docs
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -91,17 +91,42 @@ Installing from source
 
 If you are interested in contributing to Matplotlib development,
 running the latest source code, or just like to build everything
-yourself, it is not difficult to build Matplotlib from source.  Grab
-the latest *tar.gz* release file from `the PyPI files page
-<https://pypi.org/project/matplotlib/>`_, or if you want to
-develop Matplotlib or just need the latest bugfixed version, grab the
-latest git version, and see :ref:`install-from-git`.
+yourself, it is not difficult to build Matplotlib from source.
 
-Matplotlib can be installed from the source directory with a simple ::
+The easiest way to get the latest development version to start contributing
+is to go to the git `repository <https://github.com/matplotlib/matplotlib>`_
+and run::
+
+  git clone https://github.com/matplotlib/matplotlib.git
+
+If you're developing, it's better to do it in editable mode. The reason why
+is that pytest's test discovery only works for Matplotlib
+if installation is done this way. Also, editable mode allows your code changes
+to be instantly propagated to your library code without reinstalling (though
+you will have to restart your python process / kernel)::
+
+  python -m pip install -e .
+
+If you're not developing, it can be installed from the source directory with
+a simple::
 
   python -m pip install .
 
-We provide a setup.cfg_ file which you can use to customize the build
+To run the tests you will need to install some additional dependencies::
+
+  python -m pip install -r requirements/dev/dev-requirements.txt
+
+.. warning::
+
+  The following instructions in this section are for very custom
+  installations of Matplotlib. Proceed with caution because these instructions
+  may result in your build producing unexpected behavior and/or causing
+  local testing to fail.
+
+If you would like to build from a tarball, grab the latest *tar.gz* release
+file from `the PyPI files page <https://pypi.org/project/matplotlib/>`_.
+
+We provide a `setup.cfg`_ file which you can use to customize the build
 process. For example, which default backend to use, whether some of the
 optional libraries that Matplotlib ships with are installed, and so on.  This
 file will be particularly useful to those packaging Matplotlib.
@@ -113,6 +138,9 @@ file will be particularly useful to those packaging Matplotlib.
 Dependencies
 ------------
 
+Matplotlib will automatically install dependencies when you install with
+``pip``, so this section is mostly for your reference.
+
 Matplotlib requires the following dependencies:
 
 * `Python <https://www.python.org/downloads/>`_ (>= 3.6)
@@ -240,6 +268,11 @@ and on Windows:
   - ``Agg``: the Anti-Grain Geometry C++ rendering engine;
   - ``ttconv``: a TrueType font utility.
 
+If you go this route but need to reset and rebuild to change your settings,
+remember to clear your artifacts before re-building::
+
+  git clean -xfd
+
 Building on Windows
 -------------------
 
diff --git a/requirements/dev/dev-requirements.txt b/requirements/dev/dev-requirements.txt
@@ -0,0 +1,4 @@
+-r ../doc/doc-requirements.txt
+-r ../testing/travis_all.txt
+-r ../testing/travis_extra.txt
+-r ../testing/flake8.txt
