On Thu, May 19, 2011 at 6:27 PM, Benjamin Root <ben.r...@ou.edu> wrote:
> On Mon, May 16, 2011 at 5:28 PM, Benjamin Root <ben.r...@ou.edu> wrote:
>
>> On Monday, May 16, 2011, John Hunter <jdh2...@gmail.com> wrote:
>> >
>> >
>> > On Mon, May 16, 2011 at 2:52 PM, Eric Firing <efir...@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
>
>
I have made a few more small changes, and I have an additional change that I
have not committed yet. The table of contents for the examples page has
every single example titled as something like "animation example code:".
This is repeatitive and distracting. In the same spirit of removing
"matplotlib" from the titles of the api subsections, I wanted to do the same
here. I figured out how to do that without changing the actual titles of
the subsections.
So, my question is, do we want that? If so, I can push up the change to my
pull request. I still have to do some merge work apparently, but otherwise,
I think I am done with the major changes to the v1.0.x docs. Is there
anything else we want to fix before I merge this pull request?
Some other ideas I have had is to include a link to the glossary page in the
page header next to "docs", and maybe the FAQ, as well? I also want to
expand the glossary page, and comb through the docstrings to incorporate
more ":term:" usage. However, I probably want to hold off on those ideas
for the master branch.
Let me know what you all think of the docs!
Ben Root
------------------------------------------------------------------------------
What Every C/C++ and Fortran developer Should Know!
Read this article and learn how Intel has extended the reach of its
next-generation tools to help Windows* and Linux* C/C++ and Fortran
developers boost performance applications - including 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
