Re-arrange installation doc layout

QuLogic · QuLogic · commit 1b9ad3940a2f · 2021-11-26T03:57:46.000-05:00
This ensures that the ToC as generated in the PDF makes sense, and
doesn't appear in the wrong order.

Also fixes the redirect to come from the right place.
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -1,91 +1 @@
-############
-Installation
-############
-
-==============================
-Installing an official release
-==============================
-
-Matplotlib releases are available as wheel packages for macOS, Windows and
-Linux on `PyPI <https://pypi.org/project/matplotlib/>`_. Install it using
-``pip``:
-
-.. code-block:: sh
-
-  python -m pip install -U pip
-  python -m pip install -U matplotlib
-
-If this command results in Matplotlib being compiled from source and
-there's trouble with the compilation, you can add ``--prefer-binary`` to
-select the newest version of Matplotlib for which there is a
-precompiled wheel for your OS and Python.
-
-.. note::
-
-   The following backends work out of the box: Agg, ps, pdf, svg
-
-   Python is typically shipped with tk bindings which are used by
-   TkAgg.
-
-   For support of other GUI frameworks, LaTeX rendering, saving
-   animations and a larger selection of file formats, you can
-   install :ref:`optional_dependencies`.
-
-=========================
-Third-party distributions
-=========================
-
-Various third-parties provide Matplotlib for their environments.
-
-Conda packages
-==============
-Matplotlib is available both via the *anaconda main channel*
-
-.. code-block:: sh
-
-   conda install matplotlib
-
-as well as via the *conda-forge community channel*
-
-.. code-block:: sh
-
-   conda install -c conda-forge matplotlib
-
-Python distributions
-====================
-
-Matplotlib is part of major Python distributions:
-
-- `Anaconda <https://www.anaconda.com/>`_
-
-- `ActiveState ActivePython
-  <https://www.activestate.com/products/python/downloads/>`_
-
-- `WinPython <https://winpython.github.io/>`_
-
-Linux package manager
-=====================
-
-If you are using the Python version that comes with your Linux distribution,
-you can install Matplotlib via your package manager, e.g.:
-
-* Debian / Ubuntu: ``sudo apt-get install python3-matplotlib``
-* Fedora: ``sudo dnf install python3-matplotlib``
-* Red Hat: ``sudo yum install python3-matplotlib``
-* Arch: ``sudo pacman -S python-matplotlib``
-
-======================
-Installing from source
-======================
-See :ref:`install_from_source`.
-
-==========================
-Installing for development
-==========================
-See :ref:`installing_for_devs`.
-
-==============
-Installing FAQ
-==============
-
-See :ref:`installing-faq`.
+See doc/users/installing.rst
diff --git a/README.rst b/README.rst
@@ -58,8 +58,9 @@ various graphical user interface toolkits.
 Install
 =======
 
-For installation instructions and requirements, see `INSTALL.rst <INSTALL.rst>`_  or the
-`install <https://matplotlib.org/stable/users/installing.html>`_ documentation.
+For installation instructions and requirements, see the `install documentation
+<https://matplotlib.org/stable/users/installing.html>`_ or `installing.rst
+<doc/users/installing.rst>`_ in the source.
 
 Contribute
 ==========
diff --git a/doc/api/prev_api_changes/api_changes_3.1.0.rst b/doc/api/prev_api_changes/api_changes_3.1.0.rst
@@ -308,7 +308,7 @@ FreeType or libpng are not in the compiler or linker's default path, set the
 standard environment variables ``CFLAGS``/``LDFLAGS`` on Linux or OSX, or
 ``CL``/``LINK`` on Windows, to indicate the relevant paths.
 
-See details in :doc:`/users/installing/index`.
+See details in :doc:`/users/installing`.
 
 Setting artist properties twice or more in the same call
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -197,22 +197,22 @@ Documents can be linked with the ``:doc:`` directive:
 
 .. code-block:: rst
 
-   See the :doc:`/users/faq/installing_faq`
+   See the :doc:`/users/installing`
 
    See the tutorial :doc:`/tutorials/introductory/usage`
 
    See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
 
 will render as:
 
-  See the :doc:`/users/faq/installing_faq`
+  See the :doc:`/users/installing`
 
   See the tutorial :doc:`/tutorials/introductory/usage`
 
   See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
 
 Sections can also be given reference names.  For instance from the
-:doc:`/users/faq/installing_faq` link:
+:doc:`/users/installing` link:
 
 .. code-block:: rst
 
diff --git a/doc/index.rst b/doc/index.rst
@@ -34,7 +34,7 @@ Installation
 
             conda install matplotlib
 
-Further details are available in the :doc:`Installation Guide <users/installing/index>`.
+Further details are available in the :doc:`Installation Guide <users/installing>`.
 
 
 ******************
diff --git a/doc/users/getting_started/index.rst b/doc/users/getting_started/index.rst
@@ -22,7 +22,7 @@ Installation quick-start
 
             conda install matplotlib
 
-Further details are available in the :doc:`Installation Guide </users/installing/index>`.
+Further details are available in the :doc:`Installation Guide </users/installing>`.
 
 
 Draw a first plot
diff --git a/doc/users/index.rst b/doc/users/index.rst
@@ -14,7 +14,7 @@ General
    :maxdepth: 2
 
    getting_started/index.rst
-   installing/index.rst
+   installing.rst
    explain/index.rst
    faq/index.rst
    resources/index.rst
diff --git a/doc/users/installing.rst b/doc/users/installing.rst
@@ -1,13 +1,177 @@
-.. _installing-faq:
+.. redirect-from:: /users/installing/index
+
+############
+Installation
+############
+
+==============================
+Installing an official release
+==============================
+
+Matplotlib releases are available as wheel packages for macOS, Windows and
+Linux on `PyPI <https://pypi.org/project/matplotlib/>`_. Install it using
+``pip``:
+
+.. code-block:: sh
+
+  python -m pip install -U pip
+  python -m pip install -U matplotlib
+
+If this command results in Matplotlib being compiled from source and
+there's trouble with the compilation, you can add ``--prefer-binary`` to
+select the newest version of Matplotlib for which there is a
+precompiled wheel for your OS and Python.
+
+.. note::
+
+   The following backends work out of the box: Agg, ps, pdf, svg
+
+   Python is typically shipped with tk bindings which are used by
+   TkAgg.
+
+   For support of other GUI frameworks, LaTeX rendering, saving
+   animations and a larger selection of file formats, you can
+   install :ref:`optional_dependencies`.
+
+=========================
+Third-party distributions
+=========================
+
+Various third-parties provide Matplotlib for their environments.
+
+Conda packages
+==============
+Matplotlib is available both via the *anaconda main channel*
+
+.. code-block:: sh
+
+   conda install matplotlib
+
+as well as via the *conda-forge community channel*
+
+.. code-block:: sh
+
+   conda install -c conda-forge matplotlib
+
+Python distributions
+====================
+
+Matplotlib is part of major Python distributions:
+
+- `Anaconda <https://www.anaconda.com/>`_
+
+- `ActiveState ActivePython
+  <https://www.activestate.com/products/python/downloads/>`_
+
+- `WinPython <https://winpython.github.io/>`_
+
+Linux package manager
+=====================
+
+If you are using the Python version that comes with your Linux distribution,
+you can install Matplotlib via your package manager, e.g.:
+
+* Debian / Ubuntu: ``sudo apt-get install python3-matplotlib``
+* Fedora: ``sudo dnf install python3-matplotlib``
+* Red Hat: ``sudo yum install python3-matplotlib``
+* Arch: ``sudo pacman -S python-matplotlib``
+
+.. redirect-from:: /users/installing/installing_source
+
+.. _install_from_source:
+
+======================
+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.
+
+First you need to install the :ref:`dependencies`.
+
+A C compiler is required.  Typically, on Linux, you will need ``gcc``, which
+should be installed using your distribution's package manager; on macOS, you
+will need xcode_; on Windows, you will need Visual Studio 2015 or later.
+
+.. _xcode: https://guide.macports.org/chunked/installing.html#installing.xcode
+
+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
+
+or::
+
+  git clone git@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)::
+
+  cd matplotlib
+  python -m pip install -e .
+
+If you're not developing, it can be installed from the source directory with
+a simple (just replace the last step)::
+
+  python -m pip install .
+
+To run the tests you will need to install some additional dependencies::
+
+  python -m pip install -r requirements/dev/dev-requirements.txt
+
+Then, if you want to update your Matplotlib at any time, just do::
+
+  git pull
+
+When you run ``git pull``, if the output shows that only Python files have
+been updated, you are all set. If C files have changed, you need to run ``pip
+install -e .`` again to compile them.
+
+There is more information on :ref:`using git <using-git>` in the developer
+docs.
+
+.. 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 `mplsetup.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.
+
+.. _mplsetup.cfg: https://raw.githubusercontent.com/matplotlib/matplotlib/main/mplsetup.cfg.template
+
+If you are building your own Matplotlib wheels (or sdists) on Windows, note
+that any DLLs that you copy into the source tree will be packaged too.
+
+==========================
+Installing for development
+==========================
+See :ref:`installing_for_devs`.
 
 .. redirect-from:: /faq/installing_faq
+.. redirect-from:: /users/faq/installing_faq
+
+.. _installing-faq:
 
-**************
-Installing FAQ
-**************
+==========================
+Frequently Asked Questions
+==========================
 
 .. contents::
    :backlinks: none
+   :local:
 
 Report a compilation problem
 ============================
diff --git a/doc/users/installing/index.rst b/doc/users/installing/index.rst
diff --git a/doc/users/installing/installing_source.rst b/doc/users/installing/installing_source.rst
