Rewording and minor restructuring of dependencies docs

timhoffm · timhoffm · commit 4fe0e14f2551 · 2021-02-12T00:43:32.000+01:00
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -31,8 +31,8 @@ precompiled wheel for your OS and Python.
    TkAgg.
 
    For support of other GUI frameworks, LaTeX rendering, saving
-   animations and a larger selection of file formats, you need to
-   install :ref:`additional dependencies <install_requirements>`.
+   animations and a larger selection of file formats, you can
+   install :ref:`optional_dependencies`.
 
 Although not required, we suggest also installing ``IPython`` for
 interactive use.  To easily install a complete Scientific Python
diff --git a/doc/api/next_api_changes/deprecations/17662-TAC.rst b/doc/api/next_api_changes/deprecations/17662-TAC.rst
@@ -2,8 +2,8 @@ Increase minimum supported versions of Python and dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
-For Maptlotlib 3.4 the :ref:`minimum supported versions
-<install_requirements>` are being bumped
+For Maptlotlib 3.4 the :ref:`minimum supported versions <dependencies>`
+are being bumped
 
 +------------+-----------------+---------------+
 | Dependency |  min in mpl3.3  | min in mpl3.4 |
diff --git a/doc/devel/dependencies.rst b/doc/devel/dependencies.rst
@@ -1,13 +1,15 @@
-.. _install_requirements:
+.. _dependencies:
 
 ============
 Dependencies
 ============
 
-Matplotlib will automatically install dependencies when you install with
-``pip``, so this section is mostly for your reference.
+Mandatory dependencies
+======================
 
-Matplotlib requires the following dependencies:
+When installing through a package manager like ``pip`` or ``conda`` the
+mandatory dependencies are automatically installed. This list is mainly for
+reference.
 
 * `Python <https://www.python.org/downloads/>`_ (>= 3.7)
 * `NumPy <https://numpy.org>`_ (>= 1.16)
@@ -18,11 +20,20 @@ Matplotlib requires the following dependencies:
 * `Pillow <https://pillow.readthedocs.io/en/latest/>`_ (>= 6.2)
 * `pyparsing <https://pypi.org/project/pyparsing/>`_ (>=2.2.1)
 
-Optionally, you can also install a number of packages to enable better user
-interface toolkits. See :ref:`what-is-a-backend` for more details on the
-optional Matplotlib backends and the capabilities they provide.
 
-* Tk_ (>= 8.3, != 8.6.0 or 8.6.1): for the Tk-based backends.
+.. _optional_dependencies:
+
+Optional dependencies
+=====================
+
+The following packages and tools are not required but extend the capabilities
+of Matplotlib.
+
+Matplotlib figures can be rendered to various user interfaces. See
+:ref:`what-is-a-backend` for more details on the optional Matplotlib backends
+and the capabilities they provide.
+
+* Tk_ (>= 8.3, != 8.6.0 or 8.6.1) [#]_: for the Tk-based backends.
 * PyQt4_ (>= 4.6) or PySide_ (>= 1.0.3) [#]_: for the Qt4-based backends.
 * PyQt5_ or PySide2_: for the Qt5-based backends.
 * PyGObject_: for the GTK3-based backends [#]_.
@@ -42,6 +53,8 @@ optional Matplotlib backends and the capabilities they provide.
 .. _cairocffi: https://cairocffi.readthedocs.io/en/latest/
 .. _Tornado: https://pypi.org/project/tornado
 
+.. [#] Tk is part of most standard Python installations, but it's not part of
+       Python itself and thus may not be present in rare cases.
 .. [#] PySide cannot be pip-installed on Linux (but can be conda-installed).
 .. [#] If using pip (and not conda), PyGObject must be built from source; see
        https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html.
@@ -56,24 +69,31 @@ etc., you can install the following:
   animated gifs.
 * `LaTeX <https://www.latex-project.org/>`_ (with `cm-super
   <https://ctan.org/pkg/cm-super>`__ ) and `GhostScript (>=9.0)
-  <https://ghostscript.com/download/>`_ : for rendering text with
-  LaTeX.
+  <https://ghostscript.com/download/>`_ : for rendering text with LaTeX.
 * `fontconfig <https://www.fontconfig.org>`_ (>= 2.7): for detection of system
   fonts on Linux.
 
-FreeType and Qhull
-------------------
+C libraries
+===========
+
+Matplotlib brings its own copies of the following libraries:
+
+- ``Agg``: the Anti-Grain Geometry C++ rendering engine
+- ``ttconv``: a TrueType font utility
 
-Matplotlib depends on FreeType_ (>= 2.3), a font rendering library, and on
-Qhull_ (>= 2020.2), a library for computing triangulations.  By default,
-Matplotlib downloads and builds its own copies of FreeType (this is necessary
-to run the test suite, because different versions of FreeType rasterize
-characters differently) and of Qhull.  As an exception, Matplotlib defaults to
-the system version of FreeType on AIX.
+Additionally, Matplotlib depends on:
+
+- FreeType_ (>= 2.3): a font rendering library
+- QHull_ (>= 2020.2): a library for computing triangulations
 
 .. _FreeType: https://www.freetype.org/
 .. _Qhull: http://www.qhull.org/
 
+By default, Matplotlib downloads and builds its own copies of FreeType (this is
+necessary to run the test suite, because different versions of FreeType
+rasterize characters differently) and of Qhull.  As an exception, Matplotlib
+defaults to the system version of FreeType on AIX.
+
 To force Matplotlib to use a copy of FreeType or Qhull already installed in
 your system, create a :file:`setup.cfg` file with the following contents:
 
@@ -130,13 +150,6 @@ and on Windows:
    set CL=/IC:\directory\containing\ft2build.h
    set LINK=/LIBPATH:C:\directory\containing\freetype.lib
 
-.. note::
-
-  Matplotlib always uses its own copies of the following libraries:
-
-  - ``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::
 
