DOC: update documenting_mpl.rst

jklymak · jklymak · commit 06b725c0f409 · 2021-10-02T16:03:34.000+02:00
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/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -10,34 +10,44 @@ 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/`, :file:`plot_types/`, 
+: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.
 
 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.
+guide (:file:`doc/devel`), api reference (:file:`doc/api`), and examples and 
+tutorial galleries (:file:`plot_types/`, :file:`tutorials/`, and 
+:file:`examples/`). 
 
-Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from
+Sphinx_ creates ``.rst`` files that are staged in :file:`doc/api` 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.
+Similarly, the contents of :file:`doc/plot_types`, :file:`doc/gallery` and 
+:file:`doc/tutorials` are generated by the `Sphinx Gallery`_ from the 
+sources in :file:`plot_types/`, :file:`examples/` and :file:`tutorials/`.  
+These sources consist of python scripts that have ReST_ documentation built 
+into their comments.
+
+All developer-editable ``.rst`` files are 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.  If you strongly feel 
+you need a new subdirectory, you can propose to add one (and then reference 
+in the table of contents of :file:`doc/users/index.rst`). However, please do 
+not add a bare file to the top-level :file:`doc/users` without a compelling 
+reason.  
 
 .. 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,7 +191,7 @@ 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`
 
