Merge pull request matplotlib#19774 from timhoffm/doc-references

Document how to create sphinx-gallery references to examples

Author: QuLogic

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;

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
 --------------------------------
 

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`