Merge pull request matplotlib#27468 from story645/auto-backport-of-pr-27395-on-v3.8.2-doc

Manual backport of matplotlib#27395 on v3.8.2-doc

Author: QuLogic

doc/devel/development_setup.rst

@@ -155,9 +155,16 @@ Remember to activate the environment whenever you start working on Matplotlib.
 
 Install Dependencies
 ====================
+
 Most Python dependencies will be installed when :ref:`setting up the environment <dev-environment>`
 but non-Python dependencies like C++ compilers, LaTeX, and other system applications
-must be installed separately. For a full list, see :ref:`dependencies`.
+must be installed separately.
+
+.. toctree::
+  :maxdepth: 2
+
+  ../users/installing/dependencies
+
 
 Install Matplotlib in editable mode
 ===================================
@@ -178,7 +185,8 @@ also happen if you change branches) you will have to re-run
 
 If the installation is not working, please consult the :ref:`troubleshooting guide <troubleshooting-faq>`.
 If the guide does not offer a solution, please reach out via `chat <https://gitter.im/matplotlib/matplotlib>`_
-or :ref:`open an issue <submitting-a-bug-report>`.
+or :ref:`open an issue <submitting-a-bug-report>`. For a list of environment variables
+you can set before install, see :ref:`environment-variables`.
 
 Verify the Installation
 =======================

doc/devel/index.rst

@@ -97,12 +97,6 @@ Development environment
 
          development_setup
 
-      .. toctree::
-         :maxdepth: 1
-
-         dependencies
-         ../users/installing/environment_variables_faq.rst
-
 
    .. grid-item-card::
       :shadow: none

doc/devel/dependencies.rst doc/users/installing/dependencies.rstdoc/devel/dependencies.rst renamed to doc/users/installing/dependencies.rst

@@ -1,3 +1,5 @@
+.. redirect-from: /devel/dependencies
+
 .. _dependencies:
 
 ============
@@ -377,7 +379,7 @@ The additional Python packages required to build the
 
 The content of :file:`doc-requirements.txt` is also shown below:
 
-.. include:: ../../requirements/doc/doc-requirements.txt
+.. include:: ../../../requirements/doc/doc-requirements.txt
    :literal:
 
 Additional external dependencies

doc/users/installing/index.rst

@@ -1,8 +1,8 @@
 .. redirect-from:: /users/installing
 
-============
+************
 Installation
-============
+************
 
 
 Install an official release
@@ -135,25 +135,42 @@ Configure build and behavior defaults
 =====================================
 
 Aspects of the build and install process and some behaviorial defaults of the
-library can be configured via :ref:`environment-variables`. Default plotting
-appearance and behavior can be configured via the
+library can be configured via:
+
+.. toctree::
+  :maxdepth: 2
+
+  environment_variables_faq.rst
+
+Default plotting appearance and behavior can be configured via the
 :ref:`rcParams file <customizing-with-matplotlibrc-files>`
 
 
+Dependencies
+============
+
+Mandatory dependencies should be installed automatically if you install Matplotlib using
+a package manager such as ``pip`` or ``conda``; therefore this list is primarily for
+reference and troubleshooting.
+
+.. toctree::
+  :maxdepth: 2
+
+  dependencies
+
 
 .. _installing-faq:
 
-==========================
 Frequently asked questions
-==========================
+===========================
 
 Report a compilation problem
-============================
+----------------------------
 
 See :ref:`reporting-problems`.
 
 Matplotlib compiled fine, but nothing shows up when I use it
-============================================================
+------------------------------------------------------------
 
 The first thing to try is a :ref:`clean install <clean-install>` and see if
 that helps.  If not, the best way to test your install is by running a script,
@@ -175,7 +192,7 @@ If you are still having trouble, see :ref:`reporting-problems`.
 .. _clean-install:
 
 How to completely remove Matplotlib
-===================================
+-----------------------------------
 
 Occasionally, problems with Matplotlib can be solved with a clean
 installation of the package.  In order to fully remove an installed Matplotlib:
@@ -187,12 +204,12 @@ installation of the package.  In order to fully remove an installed Matplotlib:
    directory <locating-matplotlib-install>`.
 
 OSX Notes
-=========
+---------
 
 .. _which-python-for-osx:
 
 Which python for OSX?
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 Apple ships OSX with its own Python, in ``/usr/bin/python``, and its own copy
 of Matplotlib. Unfortunately, the way Apple currently installs its own copies
@@ -222,7 +239,7 @@ or Python.org Python.
 .. _install_osx_binaries:
 
 Installing OSX binary wheels
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you are using Python from https://www.python.org, Homebrew, or Macports,
 then you can use the standard pip installer to install Matplotlib binaries in
@@ -242,7 +259,7 @@ You might also want to install IPython or the Jupyter notebook (``python3 -m pip
 install ipython notebook``).
 
 Checking your installation
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The new version of Matplotlib should now be on your Python "path".  Check this
 at the Terminal.app command line::