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. >> ------------------------------------------------------------------------- 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
