updated doc/readme.txt to current layout

story645 · story645 · commit d70558c70dc5 · 2024-01-10T18:34:19.000-05:00
diff --git a/doc/README.txt b/doc/README.txt
@@ -11,33 +11,59 @@ Organization
 
 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
+python documentation system built on top of ReST.  This directory contains the
+following
 
-* users - the user documentation, e.g., installation, plotting tutorials,
-configuration tips, faq, explanations, etc.
+Files
+^^^^^
 
-* devel - documentation for Matplotlib developers
+* index.rst - the top level include document (and landing page) for the Matplotlib docs
 
-* api - placeholders to automatically generate the api documentation
+* conf.py - the sphinx configuration
 
-* 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).
+* docutils.conf - htmnl output configuration
 
-* thirdpartypackages - redirect to <https://matplotlib.org/mpl-third-party/>
+* Makefile and make.bat - entry points for building the docs
 
-* mpl_toolkits - documentation of individual toolkits that ship with
-  Matplotlib
+* matplotlibrc - rcParam configuration for docs
 
-* index.rst - the top level include document for Matplotlib docs
+* missing-references.json - list of known missing/broken references
 
-* conf.py - the sphinx configuration
 
-* Makefile and make.bat - entry points for building the docs
+Content Folders
+^^^^^^^^^^^^^^^
+
+* api - placeholders to automatically generate the api documentation
+
+* devel - documentation for contributing to Matplotlib
+
+* users - the user documentation, e.g., installation, plotting tutorials,
+configuration tips, faq, explanations, etc.
+
+* thirdpartypackages - redirect to <https://matplotlib.org/mpl-third-party/>
+
+Build Folders
+^^^^^^^^^^^^^
 
 * _static - used by the sphinx build system
 
 * _templates - used by the sphinx build system
 
 * sphinxext - Sphinx extensions for the Matplotlib docs
+
+Symlinks
+--------
+
+These folders will appear in your local version of Matplotlib after the docs have been
+built locally. sphinx-gallery generates them automatically from the documents in source
+path; therefore changes to these files must be made to the files in source path.
+
++-----------+----------------------------+
+| folder    | path to source folder      |
++-----------+----------------------------+
+|tutorials  | ``../galleries/tutorials`` |
++-----------+----------------------------+
+|plot_types | ``../galleries/plot_types  |
++-----------+----------------------------+
+|gallery    | ``../galleries/examples``  |
++-----------+----------------------------+
