reduced redundancy in headings

story645 · QuLogic · story645 · commit 0f74076cee2e · 2023-10-12T13:02:10.000-04:00
Co-authored-by: Elliott Sales de Andrade &lt;quantum.analyst@gmail.com&gt;
diff --git a/doc/devel/dependencies.rst b/doc/devel/dependencies.rst
@@ -1,15 +1,17 @@
 .. _dependencies:
 
-============
+************
 Dependencies
-============
+************
+
+.. _runtime_dependencies:
 
 Runtime dependencies
 ====================
 
 
-Mandatory dependencies
-----------------------
+Required
+--------
 
 When installing through a package manager like ``pip`` or ``conda``, the
 mandatory dependencies are automatically installed. This list is mainly for
@@ -31,8 +33,8 @@ reference.
 
 .. _optional_dependencies:
 
-Optional dependencies
----------------------
+Optional
+--------
 
 The following packages and tools are not required but extend the capabilities
 of Matplotlib.
@@ -176,9 +178,8 @@ remember to clear your artifacts before re-building::
 
   git clean -xfd
 
-
-Manual Download
-^^^^^^^^^^^^^^^
+Install from source
+^^^^^^^^^^^^^^^^^^^
 
 If the automatic download does not work (for example, on air-gapped systems) it is
 preferable to instead use system libraries. However you can manually download the
@@ -202,19 +203,21 @@ In all cases the required version of pip is embedded in the CPython source.
 
 .. _development-dependencies:
 
-Dependencies for building Matplotlib
-====================================
+Build dependencies
+==================
+
 
 .. _setup-dependencies:
 
-Setup dependencies
-------------------
+Python
+------
 
 By default, ``pip`` will build packages using build isolation, and the following
 dependencies will be automatically installed in the isolated environment to build
 Matplotlib. However, for development, you may wish to make an editable install, which
 will require disabling build isolation, so these build dependencies should be installed
-in your target environment manually:
+in the target environment manually.
+:
 
 - `meson-python <https://meson-python.readthedocs.io/>`_ (>= 0.13.1).
 - `ninja <https://ninja-build.org/>`_ (>= 1.8.2). This may be available in your package
@@ -227,14 +230,21 @@ in your target environment manually:
   Also a runtime dependency for editable installs.
 - `NumPy <https://numpy.org>`_ (>= 1.21).  Also a runtime dependency.
 
+.. note::
+
+  The Python packages listed here will be installed automatically if you are using
+  a virtual environment that was created following the instructions in :ref:`dev-environment`.
+
 
 .. _compile-dependencies:
 
-C++ compiler
+C-extensions
 ------------
 
 Matplotlib requires a C++ compiler that supports C++17, and each platform has a
 development environment that must be installed before a compiler can be installed.
+You may also need to install headers for various libraries called in the C-extension
+source files.
 
 .. tab-set::
 
@@ -294,16 +304,19 @@ Xcode, VS Code or Linux package manager. Choose **one** compiler from this list:
 
 .. _test-dependencies:
 
-Dependencies for testing Matplotlib
-===================================
+Test dependencies
+=================
+
 This section lists the additional software required for
 :ref:`running the tests <testing>`.
 
-Required:
+Required
+--------
 
 - pytest_ (>= 7.0.0)
 
-Optional:
+Optional
+--------
 
 In addition to all of the optional dependencies on the main library, for
 testing the following will be used if they are installed.
@@ -357,11 +370,12 @@ them will be skipped by pytest.
 
 .. _doc-dependencies:
 
-Dependencies for building Matplotlib's documentation
-====================================================
+Documentation dependencies
+==========================
+
+Python
+------
 
-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 ::
@@ -373,13 +387,22 @@ The content of :file:`doc-requirements.txt` is also shown below:
 .. include:: ../../requirements/doc/doc-requirements.txt
    :literal:
 
-Additional external dependencies
---------------------------------
-Required:
 
+External tools
+--------------
+
+The documentation requires 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.
+
+Required
+^^^^^^^^
+
+* `Graphviz <http://www.graphviz.org/download>`_
 * a minimal working LaTeX distribution, e.g., `TeX Live <https://www.tug.org/texlive/>`_ or
   `MikTeX <https://miktex.org/>`_
-* `Graphviz <http://www.graphviz.org/download>`_
 * the following LaTeX packages (if your OS bundles TeX Live, the
   "complete" version of the installer, e.g. "texlive-full" or "texlive-all",
   will often automatically include these packages):
@@ -388,18 +411,11 @@ Required:
   * `dvipng <https://ctan.org/pkg/dvipng>`_
   * `underscore <https://ctan.org/pkg/underscore>`_
 
-Optional, but recommended:
+Optional
+^^^^^^^^
 
 * `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/users/installing/index.rst b/doc/users/installing/index.rst
@@ -31,7 +31,7 @@ precompiled wheel for your OS and Python.
 
    For support of other GUI frameworks, LaTeX rendering, saving
    animations and a larger selection of file formats, you can
-   install :ref:`optional_dependencies`.
+   install :ref:`optional dependencies <optional_dependencies>`.
 
 
 Third-party distributions
