Merge pull request matplotlib#27631 from story645/doc-readme

DOC: update doc/readme.txt & remove devel/readme

Author: timhoffm

Diff for: doc/README.txt

@@ -9,35 +9,58 @@ See :file:`doc/devel/documenting_mpl.rst` for instructions to build the docs.
 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
+This is the top level directory for the Matplotlib
+documentation.  All of the documentation is written using Sphinx, a
+python documentation system based on reStructuredText.  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 - templates for generating the api documentation
 
-* _static - used by the sphinx build system
+* devel - documentation for contributing to Matplotlib
 
-* _templates - used by the sphinx build system
+* project - about Matplotlib, e.g. mission, code of conduct, licenses, history, etc.
+
+* users - usage documentation, e.g., installation, tutorials, faq, explanations, etc.
+
+* thirdpartypackages - redirect to <https://matplotlib.org/mpl-third-party/>
+
+Build folders
+^^^^^^^^^^^^^
+
+* _static - supplementary files; e.g. images, CSS, etc.
+
+* _templates - Sphinx page templates
 
 * sphinxext - Sphinx extensions for the Matplotlib docs
+
+Symlinks
+--------
+
+During the documentation build, sphinx-gallery creates symlinks from the source folders
+in `/galleries` to target_folders in '/doc'; therefore ensure that you are editing the
+real files rather than the symbolic links.
+
+Source files -> symlink:
+* galleries/tutorials -> doc/tutorials
+* galleries/plot_types -> doc/plot_types
+* galleries/examples -> doc/gallery
+* galleries/users_explain -> doc/users/explain