matplotlib · tacaswell · Oct 21, 2021 · Oct 21, 2021
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -2,13 +2,6 @@
 Installation
 ############
 
-.. toctree::
-   :hidden:
-
-   installing_source.rst
-   ../faq/installing_faq.rst
-
-
 ==============================
 Installing an official release
 ==============================

diff --git a/doc/README.txt b/doc/README.txt
@@ -13,15 +13,20 @@ This is the top level build directory for the Matplotlib
 documentation.  All of the documentation is written using sphinx, a
 python documentation system built on top of ReST.  This directory contains
 
-* users - the user documentation, e.g., plotting tutorials, configuration
-  tips, etc.
+* users - the user documentation, e.g., installation, plotting tutorials, 
+configuration tips, faq, explaations, etc.
 
 * devel - documentation for Matplotlib developers
 
-* faq - frequently asked questions
-
 * api - placeholders to automatically generate the api documentation
 
+* tutorials, plot_types, and gallery - automatically 
+generated by sphinx-gallery from ``../tutorials``, ``../plot_types``, and
+``../examples`` respectively (these are only present if docs have been
+built locally).  
+
+* thirdpartypackages - redirect to <https://matplotlib.org/mpl-third-party/>
+
 * mpl_toolkits - documentation of individual toolkits that ship with
   Matplotlib
 

diff --git a/doc/_templates/mpl_nav_bar.html b/doc/_templates/mpl_nav_bar.html
@@ -10,15 +10,12 @@
     <a class="reference internal nav-link" href="{{ pathto('tutorials/index') }}">Tutorials</a>
   </li>
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('api/index') }}">Reference</a>
+    <a class="reference internal nav-link" href="{{ pathto('api/index') }}">API Reference</a>
   </li>
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('users/index') }}">Usage guide</a>
+    <a class="reference internal nav-link" href="{{ pathto('users/index') }}">Users guide</a>
   </li>
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('devel/index') }}">Develop</a>
-  </li>
-  <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('users/release_notes') }}">Release notes</a>
+    <a class="reference internal nav-link" href="{{ pathto('devel/index') }}">Contributing</a>
   </li>
 </ul>
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -1,5 +1,5 @@
-Reference
-=========
+API Reference
+=============
 
 When using the library you will typically create
 :doc:`Figure <figure_api>` and :doc:`Axes <axes_api>` objects and

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`.
+See details in :doc:`/users/installing/index`.
 
 Setting artist properties twice or more in the same call
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/doc/conf.py b/doc/conf.py
@@ -213,7 +213,7 @@ def _check_dependencies():
 source_encoding = "utf-8"
 
 # The master toctree document.
-master_doc = 'contents'
+master_doc = 'users/index'
 
 # General substitutions.
 try:

diff --git a/doc/contents.rst b/doc/contents.rst
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -265,7 +265,7 @@ Other ways to contribute
 It also helps us if you spread the word: reference the project from your blog
 and articles or link to it from your website!  If Matplotlib contributes to a
 project that leads to a scientific publication, please follow the
-:doc:`/citing` guidelines.
+:doc:`/users/backmatter/citing` guidelines.
 
 .. _coding_guidelines:
 

diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -10,34 +10,35 @@ Getting started
 General file structure
 ----------------------
 
-All documentation is built from the :file:`doc/`, :file:`tutorials/`, and
-:file:`examples/` directories.  The :file:`doc/` directory contains
-configuration files for Sphinx and  reStructuredText (ReST_; ``.rst``) files
-that are rendered to documentation pages.
+All documentation is built from the :file:`doc/`.  The :file:`doc/` 
+directory contains configuration files for Sphinx and reStructuredText 
+(ReST_; ``.rst``) files that are rendered to documentation pages.
 
-
-The main entry point is :file:`doc/index.rst`, which pulls in the
-:file:`index.rst` file for the users guide (:file:`doc/users`), developers
-guide (:file:`doc/devel`), api reference (:file:`doc/api`), and FAQs
-(:file:`doc/faq`). The documentation suite is built as a single document in
-order to make the most effective use of cross referencing.
-
-Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from
+Documentation is created in three ways.  First, API documentation 
+(:file:`doc/api`) is created by Sphinx_ from
 the docstrings of the classes in the Matplotlib library.  Except for
-:file:`doc/api/api_changes/`, these ``.rst`` files are created when the
-documentation is built.
-
-Similarly, the contents of :file:`doc/gallery` and :file:`doc/tutorials` are
-generated by the `Sphinx Gallery`_ from the sources in :file:`examples/` and
-:file:`tutorials/`.  These sources consist of python scripts that have ReST_
-documentation built into their comments.
+:file:`doc/api/api_changes/`,  ``.rst`` files in :file:`doc/api` are created 
+when the documentation is built.  See :ref:`writing-docstrings` below.
+
+Second, the contents of :file:`doc/plot_types`, :file:`doc/gallery` and 
+:file:`doc/tutorials` are generated by the `Sphinx Gallery`_ from python 
+files in :file:`plot_types/`, :file:`examples/` and :file:`tutorials/`.  
+These sources consist of python scripts that have ReST_ documentation built 
+into their comments.  See :ref:`writing-examples-and-tutorials` below.  
+
+Third, Matplotlib has narrative docs written in ReST_ in subdirectories of 
+:file:`doc/users/`.  If you would like to add new documentation that is suited 
+to an ``.rst`` file rather than a gallery or tutorial example, choose an 
+appropriate subdirectory to put it in, and add the file to the table of 
+contents of :file:`index.rst` of the subdirectory.  See 
+:ref:`writing-rest-pages` below.  
 
 .. note::
 
-  Don't directly edit the ``.rst`` files in :file:`doc/gallery`,
-  :file:`doc/tutorials`, and :file:`doc/api` (excepting
-  :file:`doc/api/api_changes/`).  Sphinx_ regenerates files in these
-  directories when building documentation.
+  Don't directly edit the ``.rst`` files in :file:`doc/plot_types`,
+  :file:`doc/gallery`,  :file:`doc/tutorials`, and :file:`doc/api` 
+  (excepting :file:`doc/api/api_changes/`).  Sphinx_ regenerates 
+  files in these directories when building documentation.
 
 Setting up the doc build
 ------------------------
@@ -181,22 +182,22 @@ Documents can be linked with the ``:doc:`` directive:
 
 .. code-block:: rst
 
-   See the :doc:`/faq/installing_faq`
+   See the :doc:`/users/faq/installing_faq`
 
    See the tutorial :doc:`/tutorials/introductory/sample_plots`
 
    See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
 
 will render as:
 
-  See the :doc:`/faq/installing_faq`
+  See the :doc:`/users/faq/installing_faq`
 
   See the tutorial :doc:`/tutorials/introductory/sample_plots`
 
   See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
 
 Sections can also be given reference names.  For instance from the
-:doc:`/faq/installing_faq` link:
+:doc:`/users/faq/installing_faq` link:
 
 .. code-block:: rst
 

diff --git a/doc/index.rst b/doc/index.rst
@@ -38,7 +38,7 @@ Installation
         pip install matplotlib
 
 
-Further details are available in the :doc:`Installation Guide <users/installing>`.
+Further details are available in the :doc:`Installation Guide <users/installing/index>`.
 
 
 Learning resources
@@ -53,7 +53,7 @@ Learning resources
     - :doc:`Quick-start guide <tutorials/introductory/usage>`
     - :doc:`Plot types <plot_types/index>`
     - `Introductory tutorials <../tutorials/index.html#introductory>`_
-    - :doc:`External learning resources <resources/index>`
+    - :doc:`External learning resources <users/resources/index>`
 
     ---
 
@@ -67,7 +67,7 @@ Learning resources
     Understand how Matplotlib works
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    - The :ref:`users-guide-explain` in the :doc:`Usage guide <users/index>`
+    - The :ref:`users-guide-explain` in the :doc:`Users guide <users/index>`
     - Many of the :ref:`Intermediate <tutorials-intermediate>` and
       :ref:`Advanced <tutorials-advanced>` tutorials
       have explanatory material
@@ -106,7 +106,7 @@ you can help!
 - or improve the :ref:`documentation and code <developers-guide-index>`
 
 
-Site map
---------
+Users guide
+-----------
 
-The :ref:`complete contents of the docs <complete_sitemap>`.
+The `contents of the docs <users/index.html>`_.