From d92ab0b1658618b1ce7aa32c950366b39a63faff Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Wed, 5 Apr 2023 14:09:03 -0700 Subject: [PATCH] DOC: fix Sphinx Gallery discussion to explain mixed subddirs [ci doc] Co-authored-by: Elliott Sales de Andrade --- doc/devel/documenting_mpl.rst | 57 ++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 11 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 75b29679df8e..df7e97df661b 100644 --- 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,11 +816,30 @@ 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 -from having an plot generated insert "sgskip" somewhere in the filename. - +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 embedded 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. The last, +:file:`galleries/users_explain`, is a mixed gallery where some of the files are +raw ``*.rst`` files and some are ``*.py`` files; Sphinx Gallery just copies +these ``*.rst`` files from the source location to the build location (see +:ref:`raw_restructured_gallery`, below). + +In the Python files, to exclude an example from having a plot generated, insert +"sgskip" somewhere in the filename. Formatting the example ---------------------- @@ -947,6 +964,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 +1056,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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy