Skip to content

Document how to create sphinx-gallery references to examples #19774

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
Mar 26, 2021
Merged

Document how to create sphinx-gallery references to examples #19774

Show file tree
Hide file tree
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
2 changes: 1 addition & 1 deletion doc/_static/mpl.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -439,7 +439,7 @@ div.note {
border-color: #ccc;
}

div.seealso {
div.seealso, div.admonition-references {
background-color: #EAF1F7;
border-color: #8EADCC;
color: #3F5E7F;
Expand Down
29 changes: 29 additions & 0 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------------------------------

Expand Down
18 changes: 6 additions & 12 deletions examples/lines_bars_and_markers/fill.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll block because I don't think this creates the backlinks in matplotlib.axes.Axes.fill that are the point of this block... (https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.fill.html#examples-using-matplotlib-axes-axes-fill)

# - `matplotlib.axes.Axes.axis` / `matplotlib.pyplot.axis`