That is a somewhat deep meta-question.

I am a fan of the functionalizing as it makes it easier for people to copy-paste into their own code and use. I also think that we should be teaching users to write more intermediate-to-high level plotting functions as a general thing.

The real question to ask here is what is the target audiance / use case of the examples.

If it is to provide 80% templates of functions for users to copy-paste-modify then functionalizing makes sense.

If it is to provide a terse example of a single feature then the functionalizing does not make sense (as the idea would be users would combine several of these to get what they need).

If it is to provide an exhaustive demonstration of all possible combination and permutations of the inputs to a given function (which is more like an exhaustive unit test?) that again functionalizing does not make sense.

I am sure I am missing a use case or two of what our users actually use the examples / gallery for.

To make this long story short, I think the answer depends on the context of the example.

This might me worth sending a note to the mailing list to get more people involved in this discussion.

I am a big fan of using the gallery to demonstrate non-trivial things,
along with the usual demos that come from the API documentation. I hate the
"let me show you every single combination of features" examples in the
gallery because it obscures the "teaching moment". That being said, I do
like the examples that, for example, demonstrates all of the markers,
linestyles, line joins, etc., but only separately!

Some important features of an example (IMHO):

1. Top-level comment explaining the point of the example. If it takes more
   than three sentences, the example is likely too complicated
2. If there are multiple subplots, then an obvious comment with the
   subplot's titlename to direct me to the code for that subplot
   (sometimes, it is a function, which is also fine, but may confuse some
   readers)
3. No unnecessary "tricks". Don't be a show-off! Any necessary tricky code
   should get a comment
   (ideally, if it isn't really about "plotting", then put it off into its
   own function, or simply make it a loadable example data)
4. Maximize repeated example naming conventions (it helps to group similar
   examples),
   but minimize the "holodeck program naming scheme" (i.e.,
   embedding_in_wx{2..5}, ending every example with "demo" or "example")

There are probably more points, but this is pretty much what comes to mind.

On Fri, Mar 25, 2016 at 10:59 PM, Thomas A Caswell <notifications@github.com

wrote:

That is a somewhat deep meta-question.

I am a fan of the functionalizing as it makes it easier for people to
copy-paste into their own code and use. I also think that we should be
teaching users to write more intermediate-to-high level plotting functions
as a general thing.

The real question to ask here is what is the target audiance / use case of
the examples.

If it is to provide 80% templates of functions for users to
copy-paste-modify then functionalizing makes sense.

If it is to provide a terse example of a single feature then the
functionalizing does not make sense (as the idea would be users would
combine several of these to get what they need).

If it is to provide an exhaustive demonstration of all possible
combination and permutations of the inputs to a given function (which is
more like an exhaustive unit test?) that again functionalizing does not
make sense.

I am sure I am missing a use case or two of what our users actually use
the examples / gallery for.

To make this long story short, I think the answer depends on the context
of the example.

This might me worth sending a note to the mailing list to get more people
involved in this discussion.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#6221 (comment)

While this is open, I’ve got two quick questions about MEP12:

1. Is there any advantage to writing ReStructured Text in example docstrings? There’s at least one example with a tiny bit of ReST in its docstring and it got me wondering.
2. If I’m about to do a bunch of examples the same way, I may as well ask if you guys like it first. Does this look okay as a template for structuring the preamble part of examples?

# -*- noplot -*-

from future import __xx__

"""
A docstring summarizing what the example demonstrates.

Blah blah blah.
"""

import xxxxxx as xx
from yyyyy import zzz

# rest of the code starts here

I see no downside. We already use rst in many of our docstrings (and converting them all to use numpydoc is one of the other looming no-fun-but-very-important standing projects).

That template looks great to me.

What is the # -*- noplot -*- for?

Re: rst
Okay, I've taken a look at numpydoc format, using that for the examples shouldn't actually be too painful. I like that it's nice and readable in its raw form, that's a plus for the examples because the whole .py file gets displayed unrendered. Here's the example that had a little rst in it, by the way (.. note::).

Re: noplot
Here's the explanation I've found, and you can see it put into action here. In practice the line appears on examples that have some interactivity or don't make a plot at all, for example the webapp example linked above. I'm not adding or removing this line at all, just moving it to the top if it already exists.

I would put the docstring above all imports--unless @tacaswell says otherwise.

Yeah, I think @efiring is right that putting the future imports with the rest of the imports below the comment is better.

Okay, got it. I was wondering if there was some convention about putting future imports before docstrings because I noticed maybe a dozen examples do it that way, but PEP 236 confirms docstrings can come before future imports so that ordering sounds good.

An idea about the noplot line: if we remove the # from the regex here, we could put the noplot line inside the docstring with a little explanation like this:

"""
First line summary.

Other details here.

This line needed for correct rendering of the example page:
-*- noplot -*-
"""

from future import __xx__

import xxxxxx as xx
from yyyyy import zzz

# rest of the code starts here

I like that better because it lets us lead with the docstring for every example and it's clear to the user that that line won't do anything outside the context of building the HTML docs. If there's support for this idea, I can make a PR.

I would rather leave the 'noplot' magic as a comment. It's kind of like a shebang, and we are accustomed to those. Better to let docstrings be strictly docstrings.

Okay, got it.

attn @timhoffm @jeromefv - I think this ties into a style guide example

Note: From all the above only the first post of @tacaswell and @WeatherGod still contain relevant information. Everything else is outdated technical stuff.

This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!

attn: @esibinga

IMHO this is now covered in Examples guidelines which came in via #28527.