Skip to content

DOC: fix Sphinx Gallery discussion to explain mixed subddirs #25618

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 17, 2023
+46 −11
Merged

DOC: fix Sphinx Gallery discussion to explain mixed subddirs #25618

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 46 additions & 11 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
----------------------
Expand Down Expand Up @@ -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
=============

Expand Down Expand Up @@ -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