Re: [matplotlib-devel] Website needs love

[Benjamin R. <ben...@ou...>]

On Thu, May 19, 2011 at 6:27 PM, Benjamin Root <ben...@ou...> wrote:

> On Mon, May 16, 2011 at 5:28 PM, Benjamin Root <ben...@ou...> wrote:
>
>> On Monday, May 16, 2011, John Hunter <jd...@gm...> wrote:
>> >
>> >
>> > On Mon, May 16, 2011 at 2:52 PM, Eric Firing <ef...@ha...>
>> 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