On 05/16/2011 09:08 AM, Benjamin Root wrote: > > > On Mon, May 16, 2011 at 1:35 PM, Eric Firing <efir...@hawaii.edu > <mailto:efir...@hawaii.edu>> wrote: > > On 05/16/2011 06:56 AM, Benjamin Root wrote: > > > > > > On Tue, May 10, 2011 at 12:53 PM, John Hunter <jdh2...@gmail.com > <mailto:jdh2...@gmail.com> > > <mailto:jdh2...@gmail.com <mailto:jdh2...@gmail.com>>> wrote: > > > > > > > > On Tue, May 10, 2011 at 12:48 PM, Benjamin Root > <ben.r...@ou.edu <mailto:ben.r...@ou.edu> > > <mailto:ben.r...@ou.edu <mailto:ben.r...@ou.edu>>> wrote: > > > > > > > > > > The one thing I am confused about is what file to edit > for the > > main page. I must be very dense because I just simply > can not > > figure out where the main page is generated from. I have > been > > meaning to fix some things on the front page for a while now, > > but have been too afraid to ask. > > > > > > see doc/_templates/*.html > > > > After you have integrated the pull request into the 1.0.x branch > > (which is what I build the website from) I'll build and push > it to > > the sf site. > > > > > > Sorry it took so long. I have made those immediate fixes and pushed > > them up to my pull request. If there are any other doc fixes we > want to > > make, now would be a good time to do it. > > Ben, > > Would you add widget.py to the autogenerated API docs, please, unless > there is some reason for it to be excluded? I happened to notice that > it is missing; I haven't checked for other missing modules. > > Thank you. > > Eric > > > No problem. Having a quick view through the docs, here is what I see as > missing. Maybe some of these don't need to be included? > > > bezier.py > blocking_input.py > contour.py > finance.py > fontconfig_pattern.py > hatch.py > image.py > legend.py > lines.py > mpl.py > offsetbox.py > patches.py > patheffects.py > pylab.py > pyparsing.py > quiver.py > scale.py > table.py > texmanager.py > textpath.py > text.py > tight_bbox.py > transforms.py > widgets.py > > Some of these might not be "modules" per se, I was just doing a quick > comparison of what rst docs we have and what we have in lib/matplotlib. > Note, we are also missing api docs for backends "cairo", "cocoaagg", > "emf", "fltkagg", "gdk", "gtkcairo", "gtk", "macosx", "mixed", "ps", > "qt4", "qtagg", "qt", "svg", "tkagg", and "wx". Again, some of these > might be redundant, I am just noticing differences between the available > rst docs and the listed modules.
Ben, I had no idea this would open such a big can of worms! The strategy question here is, what do we want to include in the html API docs? It looks like the process of setting up the sphinx API docs was never completed; the present set of modules that are included ranges from the fundamental (e.g. figure.py) to the peripheral (e.g. afm.py), but I doubt that text.py, for example, was deliberately excluded. I don't see any major disadvantage to including all modules. It might make sense to present them in categories, though, instead of dumping them all into a single alphabetical list. Perhaps Mike and John will have sage advice. > > Also, I noticed that nxutils_api.rst is pretty much useless. Should I > fix that? Yes, please. I don't know how much time you have for working on the docs, but don't let the potential magnitude of the task block incremental improvements. Here is an example of another miscellaneous doc problem that was pointed out by a user: the kwarg "agg_filter" shows up all over the place in kwarg tables, with helpful description "unknown"! Now, how many of us, looking at such a table, know what "agg_filter" is, what it does, or where it comes from? It is inherited from Artist, but there is nothing in the python code, or in the src, to indicate what it is or how to use it. The magic of rgrep turns up one source of info: ./examples/pylab_examples/demo_agg_filter.py, showing that agg_filter can enable truly impressive fancy effects. Where that particular example leads is the conclusion that probably most of demo_agg_filter.py deserves to be promoted to a regular matplotlib module. That doesn't change the original problem in the docs, which is the presence of irrelevant and/or inscrutable inherited kwargs in kwarg tables. Eric > > Ben Root > ------------------------------------------------------------------------------ Achieve unprecedented app performance and reliability What every C/C++ and Fortran developer should know. Learn how Intel has extended the reach of its next-generation tools to help boost performance applications - inlcuding clusters. http://p.sf.net/sfu/intel-dev2devmay _______________________________________________ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
