DOC: fix Sphinx Gallery discussion to explain mixed subddirs [ci doc]

jklymak · jklymak · commit 899424757adf · 2023-04-05T11:19:28.000-07:00
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -20,12 +20,10 @@ the docstrings of the classes in the Matplotlib library.  Except for
 :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:`galleries/plot_types/`, :file:`galleries/examples/` and
-:file:`galleries/tutorials/`. These sources consist of python scripts that have
-ReST_ documentation built into their comments.  See
-:ref:`writing-examples-and-tutorials` below.
+Second, our example pages, tutorials, and some of the narrative documentation
+are created by `Sphinx Gallery`_.  Sphinx Gallery converts example python files
+to ``*.rst`` files with the result of Matplotlib plot calls as embedded images.
+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
@@ -818,12 +816,28 @@ code will also appear in interactive docstrings.
 Writing examples and tutorials
 ==============================
 
-Examples and tutorials are python scripts that are run by `Sphinx Gallery`_
-to create a gallery of images in the :file:`/doc/gallery` and
-:file:`/doc/tutorials` directories respectively.  To exclude an example
+Examples and tutorials are python scripts that are run by `Sphinx Gallery`_.
+Sphinx Gallery finds ``*.py`` files in source directories and runs the files to
+create images and narrative that are embeded in ``*.rst`` files in a build
+location of the :file:`doc/` directory.  Files in the build location should not
+be directly edited as they will be overwritten by Sphinx gallery. Currently
+Matplotlib has four galleries as follows:
+
+===============================  ==========================
+Source location                  Build location
+===============================  ==========================
+:file:`galleries/plot_types`     :file:`doc/plot_types`
+:file:`galleries/examples`       :file:`doc/gallery`
+:file:`galleries/tutorials`      :file:`doc/tutorials`
+:file:`galleries/users_explain`  :file:`doc/users/explain`
+===============================  ==========================
+
+The first three are traditional galleries, :file:`galleries/users_explain` is a
+mixed gallery where some of the files are raw ``*.rst`` files rather than
+``*.py`` files; Sphinx Gallery just copies those from the location to the build
+location (see :ref:`raw_restructured_gallery`, below). To exclude an example
 from having an plot generated insert "sgskip" somewhere in the filename.
 
-
 Formatting the example
 ----------------------
 
@@ -947,6 +961,23 @@ to name your example consistently, i.e. use the main function or subject
 of the example as first word in the filename; e.g. an image example
 should ideally be named similar to :file:`imshow_mynewexample.py`.
 
+.. _raw_restructured_gallery:
+
+Raw restructured text files in the gallery
+------------------------------------------
+
+`Sphinx Gallery`_ folders usually consist of a ``README.txt`` and a series of
+python source files that are then translated to an ``index.rst`` file and a
+series of ``example_name.rst`` files in the :file:`doc/` subdirectories.
+However, Sphinx Gallery also allows raw ``*.rst`` files to be passed through a
+gallery (see `Manually passing files`_ in the Sphinx Gallery documentation). We
+use this feature in :file:`galleries/users_explain`, where, for instance,
+:file:`galleries/users_explain/colors` is a regular Sphinx Gallery
+subdirectory, but  :file:`galleries/users_explain/artists` has a mix of
+``*.rst`` and ``*py`` files.  For mixed subdirectories like this, we must add
+any ``*.rst`` files to a ``:toctree:``, either in the ``README.txt`` or in a
+manual ``index.rst``.
+
 Miscellaneous
 =============
 
@@ -1022,3 +1053,4 @@ style or topbar should be made there to propagate across all subprojects.
 .. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/
 .. _references: https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html
 .. _`numpydoc docstring guide`: https://numpydoc.readthedocs.io/en/latest/format.html
+.. _`Manually passing files`: https://sphinx-gallery.github.io/stable/configuration.html#manually-passing-files
