@@ -9,35 +9,58 @@ See :file:`doc/devel/documenting_mpl.rst` for instructions to build the docs.
99Organization
1010------------
1111
12- This is the top level build directory for the Matplotlib
13- documentation. All of the documentation is written using sphinx, a
14- python documentation system built on top of ReST. This directory contains
12+ This is the top level directory for the Matplotlib
13+ documentation. All of the documentation is written using Sphinx, a
14+ python documentation system based on reStructuredText. This directory contains the
15+ following
1516
16- * users - the user documentation, e.g., installation, plotting tutorials,
17- configuration tips, faq, explanations, etc.
17+ Files
18+ ^^^^^
1819
19- *devel -documentation for Matplotlibdevelopers
20+ *index.rst -the top level include document (and landing page) forthe Matplotlibdocs
2021
21- *api -placeholders to automatically generate theapi documentation
22+ *conf.py - thesphinx configuration
2223
23- * tutorials, plot_types, and gallery - automatically
24- generated by sphinx-gallery from ``../tutorials``, ``../plot_types``, and
25- ``../examples`` respectively (these are only present if docs have been
26- built locally).
24+ * docutils.conf - htmnl output configuration
2725
28- *thirdpartypackages - redirect to <https://matplotlib.org/mpl-third-party/>
26+ *Makefile and make.bat - entry points for building the docs
2927
30- * mpl_toolkits - documentation of individual toolkits that ship with
31- Matplotlib
28+ * matplotlibrc - rcParam configuration for docs
3229
33- *index.rst -the top level include document for Matplotlib docs
30+ *missing-references.json -list of known missing/broken references
3431
35- * conf.py - the sphinx configuration
3632
37- * Makefile and make.bat - entry points for building the docs
33+ Content folders
34+ ^^^^^^^^^^^^^^^
35+
36+ * api - templates for generating the api documentation
3837
39- *_static -used by the sphinx build system
38+ *devel -documentation for contributing to Matplotlib
4039
41- * _templates - used by the sphinx build system
40+ * project - about Matplotlib, e.g. mission, code of conduct, licenses, history, etc.
41+
42+ * users - usage documentation, e.g., installation, tutorials, faq, explanations, etc.
43+
44+ * thirdpartypackages - redirect to <https://matplotlib.org/mpl-third-party/>
45+
46+ Build folders
47+ ^^^^^^^^^^^^^
48+
49+ * _static - supplementary files; e.g. images, CSS, etc.
50+
51+ * _templates - Sphinx page templates
4252
4353* sphinxext - Sphinx extensions for the Matplotlib docs
54+
55+ Symlinks
56+ --------
57+
58+ During the documentation build, sphinx-gallery creates symlinks from the source folders
59+ in `/galleries` to target_folders in '/doc'; therefore ensure that you are editing the
60+ real files rather than the symbolic links.
61+
62+ Source files -> symlink:
63+ * galleries/tutorials -> doc/tutorials
64+ * galleries/plot_types -> doc/plot_types
65+ * galleries/examples -> doc/gallery
66+ * galleries/users_explain -> doc/users/explain