Merge pull request #19774 from timhoffm/doc-references

QuLogic · web-flow · commit 7cc1e7259e3d · 2021-03-25T20:23:33.000-04:00
Document how to create sphinx-gallery references to examples
diff --git 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
@@ -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
@@ -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`

Original file line number	Diff line number	Diff line change
`@@ -439,7 +439,7 @@ div.note {`
`439`	`439`	`border-color: #ccc;`
`440`	`440`	`}`
`441`	`441`
`442`		`-div.seealso {`
	`442`	`+div.seealso, div.admonition-references {`
`443`	`443`	`background-color: #EAF1F7;`
`444`	`444`	`border-color: #8EADCC;`
`445`	`445`	`color: #3F5E7F;`