matplotlib · QuLogic · Sep 12, 2023 · Aug 30, 2023
diff --git a/doc/conf.py b/doc/conf.py
@@ -121,8 +121,7 @@ def _parse_skip_subdirs_file():
 ]
 
 exclude_patterns = [
-    'api/prev_api_changes/api_changes_*/*'
-]
+    'api/prev_api_changes/api_changes_*/*', '**/*inc.rst']
 
 exclude_patterns += skip_subdirs
 

diff --git a/doc/devel/dependencies.rst b/doc/devel/dependencies.rst
@@ -38,7 +38,7 @@ The following packages and tools are not required but extend the capabilities
 of Matplotlib.
 
 Backends
-~~~~~~~~
+^^^^^^^^
 
 Matplotlib figures can be rendered to various user interfaces. See
 :ref:`what-is-a-backend` for more details on the optional Matplotlib backends
@@ -73,14 +73,14 @@ and the capabilities they provide.
 .. _ipykernel: https://pypi.org/project/ipykernel/
 
 Animations
-~~~~~~~~~~
+^^^^^^^^^^
 
 * `ffmpeg <https://www.ffmpeg.org/>`_: for saving movies.
 * `ImageMagick <https://www.imagemagick.org/script/index.php>`_: for saving
   animated gifs.
 
 Font handling and rendering
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * `LaTeX <https://www.latex-project.org/>`_ (with `cm-super
   <https://ctan.org/pkg/cm-super>`__ and `underscore
@@ -111,7 +111,7 @@ rasterize characters differently) and of Qhull.  As an exception, Matplotlib
 defaults to the system version of FreeType on AIX.
 
 Use system libraries
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 
 To force Matplotlib to use a copy of FreeType or Qhull already installed in
 your system, create a :file:`mplsetup.cfg` file with the following contents:
@@ -185,7 +185,7 @@ remember to clear your artifacts before re-building::
 
 
 Manual Download
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 
 If the automatic download does not work (for example on air-gapped systems) it
@@ -240,17 +240,65 @@ Setup dependencies
 C++ compiler
 ------------
 
-Matplotlib requires a C++ compiler that supports C++11.
+Matplotlib requires a C++ compiler that supports C++11, and each platform has a
+development environment that must be installed before a compiler can be installed.
+
+.. tab-set::
+
+    .. tab-item:: Linux
+
+        On some Linux systems, you can install a meta-build package. For example,
+        on  Ubuntu ``apt install build-essential``
+
+        Otherwise, use the system distribution's package manager to install
+        :ref:`gcc <compiler-table>`.
+
+    .. tab-item:: macOS
+
+        Install `Xcode <https://developer.apple.com/xcode/>`_ for Apple platform development.
+
+    .. tab-item:: Windows
+
+        Install `Visual Studio Build Tools <https://visualstudio.microsoft.com/downloads/?q=build+tools>`_
+
+        Make sure "Desktop development with C++" is selected, and that the latest MSVC,
+        "C++ CMake tools for Windows," and a Windows SDK compatible with your version
+        of Windows are selected and installed. They should be selected by default under
+        the "Optional" subheading, but are required to build Matplotlib from source.
+
+        Alternatively, you can install a Linux-like environment such as `CygWin <https://www.cygwin.com/>`_
+        or `Windows Subsystem for Linux <https://learn.microsoft.com/en-us/windows/wsl/install>`_.
+
+
+We highly recommend that you install a compiler using your platform tool, i.e.,
+Xcode, VS Code or Linux package manager. Choose **one** compiler from this list:
+
+.. _compiler-table:
+
+.. list-table::
+   :widths: 20 20 20 40
+   :header-rows: 1
+
+   * - compiler
+     - minimum version
+     - platforms
+     - notes
+   * - GCC
+     - **4.8.1**
+     - Linux, macOS, Windows
+     - `gcc 4.8.1 <https://gcc.gnu.org/projects/cxx-status.html#cxx11>`_,
+       `GCC: Binaries <https://gcc.gnu.org/install/binaries.html>`_,
+
+       For gcc <6.5 you will need to set ``$CFLAGS=-std=c++11`` to enable C++11 support.
+   * - Clang (LLVM)
+     - **3.3**
+     - Linux, macOS
+     - `clang 3.3 <https://clang.llvm.org/cxx_status.html>`_, `LLVM <https://releases.llvm.org/download.html>`_
+   * - MSVC++
+     - **14.0**
+     - Windows
+     - `Visual Studio 2015 C++ <https://docs.microsoft.com/en-us/cpp/overview/visual-cpp-language-conformance?view=msvc-140>`_
 
-- `gcc 4.8.1 <https://gcc.gnu.org/projects/cxx-status.html#cxx11>`_ or higher.  For gcc <6.5 you will
-  need to set ``$CFLAGS=-std=c++11`` to enable C++11 support.
-  `Installing GCC: Binaries <https://gcc.gnu.org/install/binaries.html>`_.
-- `clang 3.3 <https://clang.llvm.org/cxx_status.html>`_ or higher.
-  `LLVM Download Page <https://releases.llvm.org/download.html>`_.
-- `Visual Studio 2015
-  <https://docs.microsoft.com/en-us/cpp/overview/visual-cpp-language-conformance?view=msvc-140>`_
-  (aka VS 14.0) or higher. A free version of Build Tools for Visual Studio is available for
-  `download <https://visualstudio.microsoft.com/downloads/?q=build+tools>`_.
 
 
 .. _test-dependencies:
@@ -286,8 +334,8 @@ testing the following will be used if they are installed.
   fonts for testing font fallback and non-western fonts
 - xarray_ used to test compatibility with xarray
 
-If any of these dependencies are not discovered the tests that rely on them
-will be skipped by pytest.
+If any of these dependencies are not discovered, then the tests that rely on
+them will be skipped by pytest.
 
 .. note::
 

diff --git a/doc/devel/development_setup.rst b/doc/devel/development_setup.rst
@@ -148,6 +148,12 @@ The simplest way to do this is to use either Python's virtual environment
 
 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`.
+
 Install Matplotlib in editable mode
 ===================================
 

diff --git a/doc/devel/index.rst b/doc/devel/index.rst
@@ -78,6 +78,7 @@ Development environment
 .. grid:: 1 1 2 2
 
    .. grid-item-card::
+      :shadow: none
 
       **Install**
       ^^^
@@ -91,9 +92,11 @@ Development environment
          :maxdepth: 1
 
          dependencies
+         ../users/installing/environment_variables_faq.rst
 
 
    .. grid-item-card::
+      :shadow: none
 
       **Workflow**
       ^^^^
@@ -103,6 +106,10 @@ Development environment
 
          development_workflow
 
+      .. toctree::
+         :maxdepth: 1
+
+         troubleshooting.rst
 
 
 .. _contribution_guideline:
@@ -115,6 +122,7 @@ Policies and guidelines
    :gutter: 2
 
    .. grid-item-card::
+      :shadow: none
 
       **Code**
       ^^^
@@ -128,6 +136,7 @@ Policies and guidelines
          testing
 
    .. grid-item-card::
+      :shadow: none
 
       **Documentation**
       ^^^
@@ -139,6 +148,7 @@ Policies and guidelines
          style_guide
 
    .. grid-item-card::
+      :shadow: none
 
       **Triage**
       ^^^
@@ -148,6 +158,7 @@ Policies and guidelines
       | :ref:`triage_workflow`
 
    .. grid-item-card::
+      :shadow: none
 
       **Maintenance**
       ^^^

diff --git a/doc/devel/troubleshooting.rst b/doc/devel/troubleshooting.rst
@@ -0,0 +1,45 @@
+.. _troubleshooting-faq:
+
+.. redirect-from:: /faq/troubleshooting_faq
+.. redirect-from:: /users/faq/troubleshooting_faq
+
+===============
+Troubleshooting
+===============
+
+For guidance on debugging an installation, see :ref:`installing-faq`.
+
+
+.. _git-trouble:
+
+Problems with git
+=================
+
+First, make sure you have a clean build and install (see :ref:`clean-install`),
+get the latest git update, install it and run a simple test script in debug
+mode::
+
+    rm -rf /path/to/site-packages/matplotlib*
+    git clean -xfd
+    git pull
+    python -m pip install -v . > build.out
+    python -c "from pylab import *; set_loglevel('debug'); plot(); show()" > run.out
+
+and post :file:`build.out` and :file:`run.out` to the `matplotlib-devel
+<https://mail.python.org/mailman/listinfo/matplotlib-devel>`_
+mailing list (please do not post git problems to the `users list
+<https://mail.python.org/mailman/listinfo/matplotlib-users>`_).
+
+Of course, you will want to clearly describe your problem, what you
+are expecting and what you are getting, but often a clean build and
+install will help.  See also :ref:`reporting-problems`.
+
+Unlink of file ``*/_c_internal_utils.cp311-win_amd64.pyd`` failed
+============================================================================
+
+The DLL files may be loaded by multiple running instances of Matplotlib; therefore
+check that Matplotlib is not running in any other application before trying to
+unlink this file. Multiple versions of Matplotlib can be linked to the same DLL,
+for example a development version installed in a development conda environment
+and a stable version running in a Jupyter notebook. To resolve this error, fully
+close all running instances of Matplotlib.
diff --git a/doc/index.rst b/doc/index.rst
@@ -56,7 +56,7 @@ Learn
             users/explain/quick_start
             User guide <users/index.rst>
             tutorials/index.rst
-            users/faq/index.rst
+            users/faq.rst
 
     .. grid-item-card::
         :padding: 2