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 ------------------------------------------------------------------------- Check out the new SourceForge.net Marketplace. It's the best place to buy or sell services for just about anything Open Source. http://sourceforge.net/services/buy/index.php _______________________________________________ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
