From 246210a956036317aaa900fced8a2c240a9cf120 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Thu, 25 Mar 2021 23:38:06 +0100
Subject: [PATCH] Document how to create sphinx-gallery references to examples

Closes #19232.
---
 doc/_static/mpl.css                     |  2 +-
 doc/devel/documenting_mpl.rst           | 29 +++++++++++++++++++++++++
 examples/lines_bars_and_markers/fill.py | 18 +++++----------
 3 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css
index 63e99e52fa26..47f70a73f5be 100644
--- a/doc/_static/mpl.css
+++ b/doc/_static/mpl.css
@@ -439,7 +439,7 @@ div.note {
     border-color: #ccc;
 }
 
-div.seealso {
+div.seealso, div.admonition-references {
     background-color: #EAF1F7;
     border-color: #8EADCC;
     color: #3F5E7F;
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
index 51997ef501bb..766f181ff31e 100644
--- a/doc/devel/documenting_mpl.rst
+++ b/doc/devel/documenting_mpl.rst
@@ -859,6 +859,35 @@ are delimited by a line of ``###`` characters:
 
 In this way text, code, and figures are output in a "notebook" style.
 
+References for sphinx-gallery
+-----------------------------
+
+The showcased Matplotlib functions should be listed in an admonition at the
+bottom as follows
+
+.. code-block:: python
+
+    ###############################################################################
+    #
+    # .. admonition:: References
+    #
+    #    The use of the following functions, methods, classes and modules is shown
+    #    in this example:
+    #
+    #    - `matplotlib.axes.Axes.fill` / `matplotlib.pyplot.fill`
+    #    - `matplotlib.axes.Axes.axis` / `matplotlib.pyplot.axis`
+
+This allows sphinx-gallery to place an entry to the example in the
+mini-gallery of the mentioned functions. Whether or not a function is mentioned
+here should be decided depending on if a mini-gallery link prominently helps
+to illustrate that function; e.g. mention ``matplotlib.pyplot.subplots`` only
+in examples that are about laying out subplots, not in every example that uses
+it.
+
+Functions that exist in ``pyplot`` as well as in Axes or Figure should mention
+both references no matter which one is used in the example code. The ``pyplot``
+reference should always be the second to mention; see the example above.
+
 Order of examples in the gallery
 --------------------------------
 
diff --git a/examples/lines_bars_and_markers/fill.py b/examples/lines_bars_and_markers/fill.py
index e6d2e4293f35..158a16f863d9 100644
--- a/examples/lines_bars_and_markers/fill.py
+++ b/examples/lines_bars_and_markers/fill.py
@@ -76,18 +76,12 @@ def _koch_snowflake_complex(order):
 
 plt.show()
 
-#############################################################################
+###############################################################################
 #
-# ------------
+# .. admonition:: References
 #
-# References
-# """"""""""
+#    The use of the following functions, methods, classes and modules is shown
+#    in this example:
 #
-# The use of the following functions, methods, classes and modules is shown
-# in this example:
-
-import matplotlib
-matplotlib.axes.Axes.fill
-matplotlib.pyplot.fill
-matplotlib.axes.Axes.axis
-matplotlib.pyplot.axis
+#    - `matplotlib.axes.Axes.fill` / `matplotlib.pyplot.fill`
+#    - `matplotlib.axes.Axes.axis` / `matplotlib.pyplot.axis`