matplotlib · story645 · Jan 6, 2021 · Jan 2, 2021
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -74,81 +74,6 @@ Matplotlib is an open source project with limited resources, we encourage
 users to then also
 :ref:`participate in the implementation <contributing-code>`.
 
-.. _installing_for_devs:
-
-Retrieving and installing the latest version of the code
-========================================================
-
-When developing Matplotlib, sources must be downloaded, built, and installed
-into a local environment on your machine.
-
-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 (see
-:ref:`set-up-fork` for more details)::
-
-    git clone https://github.com/matplotlib/matplotlib.git
-
-and navigate to the :file:`matplotlib` directory. If you have the proper privileges,
-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.
-
-Installing Matplotlib in developer mode
----------------------------------------
-
-It is strongly recommended to set up a clean `virtual environment`_.  Do not
-use on a preexisting environment!
-
-A new environment can be set up with ::
-
-   python3 -mvenv <file folder location>
-
-and activated with one of the following::
-
-   source <file folder location>/bin/activate  # Linux/macOS
-   <file folder location>\Scripts\activate.bat  # Windows cmd.exe
-   <file folder location>\Scripts\Activate.ps1  # Windows PowerShell
-
-Whenever you plan to work on Matplotlib, remember to activate the development
-environment in your shell!
-
-To install Matplotlib (and compile the C-extensions) run the following
-command from the top-level directory ::
-
-   python -mpip install -ve .
-
-This installs Matplotlib in 'editable/develop mode', i.e., builds
-everything and places the correct link entries in the install
-directory so that python will be able to import Matplotlib from the
-source 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_ext --inplace
-
-or re-run ``python -mpip install -ve .``.
-
-You can then run the tests to check your work environment is set up properly::
-
-   python -mpytest
-
-.. _virtual environment: https://docs.python.org/3/library/venv.html
-.. _pytest: http://doc.pytest.org/en/latest/
-.. _pep8: https://pep8.readthedocs.io/en/latest/
-.. _Ghostscript: https://www.ghostscript.com/
-.. _Inkscape: https://inkscape.org/
-
-.. note::
-
-  **Additional dependencies for testing**: pytest_ (version 3.6 or later),
-  Ghostscript_, Inkscape_
-
-.. seealso::
-
-  * :ref:`testing`
-
 .. _contributing-code:
 
 Contributing code

diff --git a/doc/devel/development_setup.rst b/doc/devel/development_setup.rst
@@ -0,0 +1,135 @@
+.. _installing_for_devs:
+
+=====================================
+Setting up Matplotlib for development
+=====================================
+
+.. _dev-environment:
+
+Creating a dedicated environment
+================================
+You should set up a dedicated environment to decouple your Matplotlib
+development from other Python and Matplotlib installations on your system.
+Here we use python's virtual environment `venv`_, but you may also use others
+such as conda.
+
+.. _venv: https://docs.python.org/3/library/venv.html
+
+A new environment can be set up with ::
+
+   python -m venv <file folder location>
+
+and activated with one of the following::
+
+   source <file folder location>/bin/activate  # Linux/macOS
+   <file folder location>\Scripts\activate.bat  # Windows cmd.exe
+   <file folder location>\Scripts\Activate.ps1  # Windows PowerShell
+
+Whenever you plan to work on Matplotlib, remember to activate the development
+environment in your shell.
+
+Retrieving the latest version of the code
+=========================================
+
+Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git.
+
+You can retrieve the latest sources with the command (see
+:ref:`set-up-fork` for more details)::
+
+    git clone https://github.com/matplotlib/matplotlib.git
+
+This will place the sources in a directory :file:`matplotlib` below your
+current working directory.
+
+If you have the proper privileges, 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.
+
+Installing Matplotlib in editable mode
+======================================
+Install Matplotlib in editable mode from the :file:`matplotlib` directory
+using the command ::
+
+    python -m pip install -ve .
+
+The 'editable/develop mode', builds everything and places links in your Python
+environment so that Python will be able to import Matplotlib from your
+development source directory.  This allows you to import your modified version
+of Matplotlib without re-installing after every change. Note that this is only
+true for ``*.py`` files.  If you change the C-extension source (which might
+also happen if you change branches) you will have to re-run
+``python -mpip install -ve .``
+
+.. _test-dependencies:
+
+Additional dependencies for testing
+===================================
+This section lists the additional software required for
+:ref:`running the tests <testing>`.
+
+Required:
+
+- pytest_ (>=3.6)
+- Ghostscript_ (>= 9.0, to render PDF files)
+- Inkscape_ (to render SVG files)
+
+Optional:
+
+- pytest-cov_ (>=2.3.1) to collect coverage information
+- pytest-flake8_ to test coding standards using flake8_
+- pytest-timeout_ to limit runtime in case of stuck tests
+- pytest-xdist_ to run tests in parallel
+
+.. _pytest: http://doc.pytest.org/en/latest/
+.. _Ghostscript: https://www.ghostscript.com/
+.. _Inkscape: https://inkscape.org
+.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
+.. _pytest-flake8: https://pypi.org/project/pytest-flake8/
+.. _pytest-xdist: https://pypi.org/project/pytest-xdist/
+.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
+.. _flake8: https://pypi.org/project/flake8/
+
+
+.. _doc-dependencies:
+
+Additional dependencies for building documentation
+==================================================
+
+Python packages
+---------------
+The additional Python packages required to build the
+:ref:`documentation <documenting-matplotlib>` are listed in
+:file:`doc-requirements.txt` and can be installed using ::
+
+    pip install -r requirements/doc/doc-requirements.txt
+
+The content of :file:`doc-requirements.txt` is also shown below:
+
+   .. include:: ../../requirements/doc/doc-requirements.txt
+      :literal:
+
+Additional external dependencies
+--------------------------------
+Required:
+
+*  a minimal working LaTeX distribution
+*  `Graphviz <http://www.graphviz.org/download>`_
+*  the LaTeX packages *cm-super* and *dvipng*. If your OS bundles ``TexLive``,
+   then often the "complete" version of the installer will automatically include
+   these packages (e.g. "texlive-full" or "texlive-all").
+
+Optional, but recommended:
+
+*  `Inkscape <https://inkscape.org>`_
+*  `optipng <http://optipng.sourceforge.net>`_
+*  the font "Humor Sans" (aka the "XKCD" font), or the free alternative
+   `Comic Neue <http://comicneue.com/>`_.
+*  the font "Times New Roman"
+
+.. note::
+
+  The documentation will not build without LaTeX and Graphviz.  These are not
+  Python packages and must be installed separately. The documentation can be
+  built without Inkscape and optipng, but the build process will raise various
+  warnings. If the build process warns that you are missing fonts, make sure
+  your LaTeX distribution bundles cm-super or install it separately.
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -14,7 +14,6 @@ Writing documentation
 Getting started
 ===============
 
-
 General file structure
 ----------------------
 
@@ -51,55 +50,12 @@ Setting up the doc build
 ------------------------
 
 The documentation for Matplotlib is generated from reStructuredText (ReST_)
-using the Sphinx_ documentation generation tool. To build the documentation
-you will need to
-
-1. set up an appropriate Python environment
-2. install additional external dependencies
-
-Setting up a dedicated Python environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*  create a clean virtual environment with no existing Matplotlib installation
-*  install the Python packages required for Matplotlib
-*  install the additional Python packages required to build the documentation.
-   They are listed in :file:`doc-requirements.txt`, which is shown below:
-
-   .. include:: ../../requirements/doc/doc-requirements.txt
-      :literal:
-
-.. note::
-
-  If you've already set up an
-  :ref:`environment for Matplotlib development <installing_for_devs>`, you
-  can reuse that and skip the first two steps.
-
-Install additional external dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Required:
-
-*  a minimal working LaTeX distribution
-*  `Graphviz <http://www.graphviz.org/download>`_
-*  the LaTeX packages *cm-super* and *dvipng*. If your OS bundles ``TexLive``,
-   then often the "complete" version of the installer will automatically include
-   these packages (e.g. "texlive-full" or "texlive-all").
-
-Optional, but recommended:
-
-*  `Inkscape <https://inkscape.org>`_
-*  `optipng <http://optipng.sourceforge.net>`_
-*  the font "Humor Sans" (aka the "XKCD" font), or the free alternative
-   `Comic Neue <http://comicneue.com/>`_.
-*  the font "Times New Roman"
-
-.. note::
+using the Sphinx_ documentation generation tool.
 
-  The documentation will not build without LaTeX and Graphviz.  These are not
-  Python packages and must be installed separately. The documentation can be
-  built without Inkscape and optipng, but the build process will raise various
-  warnings. If the build process warns that you are missing fonts, make sure
-  your LaTeX distribution bundles cm-super or install it separately.
+To build the documentation you will need to
+:ref:`set up Matplotlib for development <installing_for_devs>`. Note in
+particular the :ref:`additional dependencies <doc-dependencies>` required to
+build the documentation.
 
 Building the docs
 -----------------

diff --git a/doc/devel/index.rst b/doc/devel/index.rst
@@ -18,6 +18,7 @@ The Matplotlib Developers' Guide
 
    contributing.rst
    triage.rst
+   development_setup.rst
    testing.rst
    documenting_mpl.rst
    add_new_projection.rst

diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -9,33 +9,20 @@ Matplotlib's testing infrastructure depends on pytest_. The tests are in
 infrastructure are in :mod:`matplotlib.testing`.
 
 .. _pytest: http://doc.pytest.org/en/latest/
-.. _Ghostscript: https://www.ghostscript.com/
-.. _Inkscape: https://inkscape.org
-.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
 .. _pytest-flake8: https://pypi.org/project/pytest-flake8/
 .. _pytest-xdist: https://pypi.org/project/pytest-xdist/
 .. _pytest-timeout: https://pypi.org/project/pytest-timeout/
 .. _flake8: https://pypi.org/project/flake8/
 
-Requirements
-------------
-
-Install the latest version of Matplotlib as documented in
-:ref:`installing_for_devs`.
-
-The following software is required to run the tests:
 
-- pytest_ (>=3.6)
-- Ghostscript_ (>= 9.0, to render PDF files)
-- Inkscape_ (to render SVG files)
+.. _testing_requirements:
 
-Optionally you can install:
-
-- pytest-cov_ (>=2.3.1) to collect coverage information
-- pytest-flake8_ to test coding standards using flake8_
-- pytest-timeout_ to limit runtime in case of stuck tests
-- pytest-xdist_ to run tests in parallel
+Requirements
+------------
 
+To run the tests you will need to
+:ref:`set up Matplotlib for development <installing_for_devs>`. Note in
+particular the :ref:`additional dependencies <test-dependencies>` for testing.
 
 Running the tests
 -----------------