On Mon, May 16, 2011 at 5:28 PM, Benjamin Root <ben.root@ou.edu> wrote:
On Monday, May 16, 2011, John Hunter <jdh2358@gmail.com> wrote:
>
>
> On Mon, May 16, 2011 at 2:52 PM, Eric Firing <efiring@hawaii.edu> wrote:
>
>
>
> 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.
>
>
> Not all of the doc strings have been converted to rest.  Back when I was actively working on the docs, I would add a module to the API table of contents when I had at least done a first pass at converting the docs to rest.  This isn't a requirement, but it helps explain why some modules and not others are in the list.
>

Well, I will take a look at what is currently converted and see if any
of those can get added.

Ben Root

Ok, on my pull request, I have made a number of commits.  In particular, I have ReST-ified widgets.py (although there are still some more things to do in it).  I have added a widgets api file to the api docs, and also renamed the headers for each api file so that the "matplotlib" part didn't show up repeatedly in the ToC.

There are still plenty of odds and ends that can be done.  I want to clean up the examples page so that the "matplotlib: " string doesn't show up for every entry as well.  Furthermore, the widgets module has some docstrings that seems like the author got distracted halfway through writing it and never came back.  I marked those docstrings with FIXME comments.

Let me know what you all think!

Ben Root