I noticed Michael just made a commit adding plot directive examples in
the doc strings. I think this is a great idea, and very cool, since
the html docs for a given function will not only link to a complete
code example, but also have inline figures and links to various output
high res or vector formats. See for example, at the bottom of the
help for the hexbin function
http://matplotlib.sourceforge.net/doc/html/api/axes_api.html#matplotlib.axes.Axes.hexbin
or
http://matplotlib.sourceforge.net/doc/html/api/pyplot_api.html#matplotlib.pyplot.hexbin
but I'd like to encourage everyone to clean up the examples they link
to, preferably so that they use the recommended idioms
import numpy as np
import matplotlib.pyplot as plt
Having a bunch of 'from pylab import *' code in our examples is
probably not a good idea as we are trying to encourage new users to be
more explicit about namespaces.
We may also want to consider explicitly putting examples we literal
include into pyplots rather than linking to them through the
mpl_examples dir so we have more control over them vis-a-vis making
sure they look good at the rendered sizes and helping prevent
developers not working on the docs from inadvertently making changes
to the example that foul up the docs. I have mixed feelings about
this last point because of the redundancy -- the alternative is just
to clean them in place and makes sure developers know not to much with
them w/o checking the effect on the docs.
But these minor nits aside, a very good idea Michael.
JDH
I was just about to write an e-mail about this. I just put a few in to see what would blow up on other people's machines... 
Like John, I also have mixed feelings about moving the examples to pyplots.
Maybe we need a new subdirectory under examples called "doc_examples" or something, and examples that are part of the docs get *moved*, not copied, into there. Not a great solution either, but I'd hate for either the doc examples or regular examples to get neglected or out-of-sync just because there's now two very similar things to update.
A related issue with using some of the existing examples directly is that they are multi-figure, which the documentation infrastructure doesn't easily support -- plus, I don't think we want 7 examples for a single function inline in the docs anyway. But it might be nice, for example, to include an example of common usage, and then a link to more advanced features.
Cheers,
Mike
John Hunter wrote:
···
I noticed Michael just made a commit adding plot directive examples in
the doc strings. I think this is a great idea, and very cool, since
the html docs for a given function will not only link to a complete
code example, but also have inline figures and links to various output
high res or vector formats. See for example, at the bottom of the
help for the hexbin function
http://matplotlib.sourceforge.net/doc/html/api/axes_api.html#matplotlib.axes.Axes.hexbin
or
http://matplotlib.sourceforge.net/doc/html/api/pyplot_api.html#matplotlib.pyplot.hexbin
but I'd like to encourage everyone to clean up the examples they link
to, preferably so that they use the recommended idioms
import numpy as np
import matplotlib.pyplot as plt
Having a bunch of 'from pylab import *' code in our examples is
probably not a good idea as we are trying to encourage new users to be
more explicit about namespaces.
We may also want to consider explicitly putting examples we literal
include into pyplots rather than linking to them through the
mpl_examples dir so we have more control over them vis-a-vis making
sure they look good at the rendered sizes and helping prevent
developers not working on the docs from inadvertently making changes
to the example that foul up the docs. I have mixed feelings about
this last point because of the redundancy -- the alternative is just
to clean them in place and makes sure developers know not to much with
them w/o checking the effect on the docs.
But these minor nits aside, a very good idea Michael.
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA
Michael Droettboom wrote:
I was just about to write an e-mail about this. I just put a few in to see what would blow up on other people's machines...
Like John, I also have mixed feelings about moving the examples to pyplots.
Maybe we need a new subdirectory under examples called "doc_examples" or something, and examples that are part of the docs get *moved*, not copied, into there. Not a great solution either, but I'd hate for either the doc examples or regular examples to get neglected or out-of-sync just because there's now two very similar things to update.
I think a special place for doc examples is a very good idea; I don't see any real disadvantage.
Eric
···
A related issue with using some of the existing examples directly is that they are multi-figure, which the documentation infrastructure doesn't easily support -- plus, I don't think we want 7 examples for a single function inline in the docs anyway. But it might be nice, for example, to include an example of common usage, and then a link to more advanced features.
Cheers,
Mike
John Hunter wrote:
I noticed Michael just made a commit adding plot directive examples in
the doc strings. I think this is a great idea, and very cool, since
the html docs for a given function will not only link to a complete
code example, but also have inline figures and links to various output
high res or vector formats. See for example, at the bottom of the
help for the hexbin function
http://matplotlib.sourceforge.net/doc/html/api/axes_api.html#matplotlib.axes.Axes.hexbin
or
http://matplotlib.sourceforge.net/doc/html/api/pyplot_api.html#matplotlib.pyplot.hexbin
but I'd like to encourage everyone to clean up the examples they link
to, preferably so that they use the recommended idioms
import numpy as np
import matplotlib.pyplot as plt
Having a bunch of 'from pylab import *' code in our examples is
probably not a good idea as we are trying to encourage new users to be
more explicit about namespaces.
We may also want to consider explicitly putting examples we literal
include into pyplots rather than linking to them through the
mpl_examples dir so we have more control over them vis-a-vis making
sure they look good at the rendered sizes and helping prevent
developers not working on the docs from inadvertently making changes
to the example that foul up the docs. I have mixed feelings about
this last point because of the redundancy -- the alternative is just
to clean them in place and makes sure developers know not to much with
them w/o checking the effect on the docs.
But these minor nits aside, a very good idea Michael.
I'm not real keen on this if it means moving the example from the
existing location, since the examples directory should be organized to
help the users learn rather than as a convenience to the developer.
The "doc_example" is not to useful to the user, who should be thinking
in terms of "pylab" or "api" or "dates" or "events" or "images". I
think I prefer in-place references or copies over this.
JDH
···
On Thu, Jun 26, 2008 at 3:14 PM, Eric Firing <efiring@...229...> wrote:
I think a special place for doc examples is a very good idea; I don't see
any real disadvantage.
Wow, guys this is really cool. I do hope that you are going to talk about
this at the SciPy08 conference. This is solid gold, IMHO.
Ga�l
···
On Thu, Jun 26, 2008 at 01:50:29PM -0500, John Hunter wrote:
I noticed Michael just made a commit adding plot directive examples in
the doc strings. I think this is a great idea, and very cool, since
the html docs for a given function will not only link to a complete
code example, but also have inline figures and links to various output
high res or vector formats. See for example, at the bottom of the
help for the hexbin function
http://matplotlib.sourceforge.net/doc/html/api/axes_api.html#matplotlib.axes.Axes.hexbin