As I continue to put together my tutorial for SciPy 2013, I have come to realize several things that are lacking with our documentation. First of all, while the pyplot summary table: http://matplotlib.org/1.3.0/api/pyplot_summary.html is a great addition, it is still a huge mis-mash of different kinds of functions. Some functions are for plotting, others are for figure and axes prep, and others are for decorating the plot. I am just about done with my reorganized list and will post it for others to comment and possibly include for that page.
Second, if there is one thing that Matlab gets right, it is its documentation. Let’s compare the doc page for the hist() function:
First off, I think there is some sort of error in the docstring because the sphinx rendering is a bit messed up. Second, in the matlab doc page, there is a dead simple, complete, concise example for each call signature, and an image of the plot to go with it.
I think this is key. I am finding some functions that have examples that demonstrate more than just the plotting function, i.e., hexbin(), or are missng examples altogether, i.e., matshow() and pie().
So, my proposal is this. For every plotting function, there should be a minimalist, complete example available to demonstrate it. Further, that example and its result should be easily viewable from the function’s documentation. For organization’s sake, I would suggest having a consistent naming scheme for this kind of example. Lastly, such an example should be required as part of any pull request to add new plotting functions.
As a side note related to “easily viewable example code”, one thing I don’t like about the examples in the doc strings is that they don’t provide me a link to one of these pages: http://matplotlib.org/1.3.0/examples/pie_and_polar_charts/pie_demo_features.html. Those pages are nice because I can see the code and the image it produces at the same time. Instead, those API doc pages just gives me a link to download the source code, or to view the image. Is it at all possible to have the example sphinx directive include a link to those example pages when rendering the API documentation?