DOC: update documenting_mpl.rst

jklymak · jklymak · commit 9b9dfaeeeded · 2021-10-02T18:06:39.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,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,7 +182,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`
 
