Website needs love

Development matplotlib-devel
1

The website is quite out of date. Not only does it claim that the latest
release is 1.0.0, but the link to the github repository appears to be
broken (has unneeded .git at the end of it).

Cheers,

- Ben

2

Is the website itself in the git repository? If so, I suppose someone could just fork it and make a pull request.

Jason

···

On 5/10/11 9:43 AM, Ben Gamari wrote:

The website is quite out of date. Not only does it claim that the latest
release is 1.0.0, but the link to the github repository appears to be
broken (has unneeded .git at the end of it).

3

The documentation is a part of the matplotlib package. The website is generated from that information and uploaded to the sourceforge site. I have been doing some work on other pages (see https://github.com/matplotlib/matplotlib/pull/102 ). Please use this branch of mine to make small changes so that we can bring all of the changes into the docs at once.

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.

Ben Root

···

On Tue, May 10, 2011 at 12:42 PM, Jason Grout <jason-sage@…691…> wrote:

On 5/10/11 9:43 AM, Ben Gamari wrote:

The website is quite out of date. Not only does it claim that the latest

release is 1.0.0, but the link to the github repository appears to be

broken (has unneeded .git at the end of it).

Is the website itself in the git repository? If so, I suppose someone

could just fork it and make a pull request.

Jason

4

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.

···

On Tue, May 10, 2011 at 12:48 PM, Benjamin Root <ben.root@…553…> 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.

5

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 Root

···

On Tue, May 10, 2011 at 12:53 PM, John Hunter <jdh2358@…272…149…> wrote:

On Tue, May 10, 2011 at 12:48 PM, Benjamin Root <ben.root@…553…> 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.

6

        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

···

On 05/16/2011 06:56 AM, Benjamin Root wrote:

On Tue, May 10, 2011 at 12:53 PM, John Hunter <jdh2358@...149... > <mailto:jdh2358@…149…>> wrote:
    On Tue, May 10, 2011 at 12:48 PM, Benjamin Root <ben.root@...553... > <mailto:ben.root@…553…>> wrote:

Ben Root

7

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.

Also, I noticed that nxutils_api.rst is pretty much useless. Should I fix that?

Ben Root

···

On Mon, May 16, 2011 at 1:35 PM, Eric Firing <efiring@…552…229…> wrote:

On 05/16/2011 06:56 AM, Benjamin Root wrote:

On Tue, May 10, 2011 at 12:53 PM, John Hunter <jdh2358@…149… > > mailto:jdh2358@...149...> wrote:

On Tue, May 10, 2011 at 12:48 PM, Benjamin Root <ben.root@...553... > >     <mailto:ben.root@...553...>> 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

8

Corrections…

fontconfig_pattern is included in font_manager_api.rst
legend, lines, patches and text are included in artist_api.rst. However, legend is not included for the inheritance diagram.

Also, ‘spines’ is listed as ‘spine’. I don’t know if that impacts anything, but I am a stickler for consistency. Should this be fixed?

Ben Root

···

On Mon, May 16, 2011 at 2:08 PM, Benjamin Root <ben.root@…553…> wrote:

On Mon, May 16, 2011 at 1:35 PM, Eric Firing <efiring@…229…> wrote:

On 05/16/2011 06:56 AM, Benjamin Root wrote:

On Tue, May 10, 2011 at 12:53 PM, John Hunter <jdh2358@…149… > > > mailto:jdh2358@...149...> wrote:

On Tue, May 10, 2011 at 12:48 PM, Benjamin Root <ben.root@...553... > > >     <mailto:ben.root@...553...>> 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.

Also, I noticed that nxutils_api.rst is pretty much useless. Should I fix that?

Ben Root

9

     >
     > 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

···

On 05/16/2011 09:08 AM, Benjamin Root wrote:

On Mon, May 16, 2011 at 1:35 PM, Eric Firing <efiring@...229... > <mailto:efiring@…229…>> wrote:
    On 05/16/2011 06:56 AM, Benjamin Root wrote:
     > On Tue, May 10, 2011 at 12:53 PM, John Hunter <jdh2358@...149... > <mailto:jdh2358@…149…> > > <mailto:jdh2358@…149…>> wrote:
     > On Tue, May 10, 2011 at 12:48 PM, Benjamin Root > <ben.root@...553... <mailto:ben.root@…553…> > > <mailto:ben.root@…553…>> wrote:

Ben Root

10

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.

···

On Mon, May 16, 2011 at 2:52 PM, Eric Firing <efiring@…552…229…> 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.

11

         >
         > 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.

    Also, I noticed that nxutils_api.rst is pretty much useless. Should
    I fix that?

    Ben Root

Corrections....

fontconfig_pattern is included in font_manager_api.rst
legend, lines, patches and text are included in artist_api.rst.
However, legend is not included for the inheritance diagram.

Aha!

So, part of the problem here is that the contents list for "The Matplotlib API" is full of names like "matplotlib_axes", which is a module, and "matplotlib_artists", which documents a hierarchy of modules inheriting from Artist--but by no means all such modules, since others, like collections, stand alone. First, having all those "matplotlib_" prefixes is distracting and makes it harder to find the information. Second, the overall hierarchy is very inconsistent, with big categories ("artists") alongside details ("gridspec").

Also, 'spines' is listed as 'spine'. I don't know if that impacts
anything, but I am a stickler for consistency. Should this be fixed?

Yes.

Eric

···

On 05/16/2011 09:32 AM, Benjamin Root wrote:

On Mon, May 16, 2011 at 2:08 PM, Benjamin Root <ben.root@...553... > <mailto:ben.root@…553…>> wrote:
    On Mon, May 16, 2011 at 1:35 PM, Eric Firing <efiring@...229... > <mailto:efiring@…229…>> wrote:
        On 05/16/2011 06:56 AM, Benjamin Root wrote:
         > On Tue, May 10, 2011 at 12:53 PM, John Hunter > <jdh2358@...149... <mailto:jdh2358@…149…> > > <mailto:jdh2358@…149…>> wrote:
         > On Tue, May 10, 2011 at 12:48 PM, Benjamin Root > <ben.root@...553... <mailto:ben.root@…553…> > > <mailto:ben.root@…553…>> wrote:

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
matplotlib-devel List Signup and Options

12 
     &gt;
     &gt;
     &gt;
     &gt;
     &gt;
     &gt;
     &gt;
     &gt;
     &gt;
     &gt;         The one thing I am confused about is what file to
    edit for the
     &gt;         main page\.  I must be very dense because I just
    simply can not
     &gt;         figure out where the main page is generated from\.  I
    have been
     &gt;         meaning to fix some things on the front page for a
    while now,
     &gt;         but have been too afraid to ask\.
     &gt;
     &gt;
     &gt;     see doc/\_templates/\*\.html
     &gt;
     &gt;     After you have integrated the pull request into the 1\.0\.x
    branch
     &gt;     \(which is what I build the website from\) I&#39;ll build and
    push it to
     &gt;     the sf site\.
     &gt;
     &gt;
     &gt; Sorry it took so long\.  I have made those immediate fixes and
    pushed
     &gt; them up to my pull request\.  If there are any other doc fixes
    we want to
     &gt; 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&#39;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&#39;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 &quot;modules&quot; 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
&quot;cairo&quot;, &quot;cocoaagg&quot;, &quot;emf&quot;, &quot;fltkagg&quot;, &quot;gdk&quot;, &quot;gtkcairo&quot;, &quot;gtk&quot;,
&quot;macosx&quot;, &quot;mixed&quot;, &quot;ps&quot;, &quot;qt4&quot;, &quot;qtagg&quot;, &quot;qt&quot;, &quot;svg&quot;, &quot;tkagg&quot;, and
&quot;wx&quot;\.  Again, some of these might be redundant, I am just noticing
differences between the available rst docs and the listed modules\.

Also, I noticed that nxutils\_api\.rst is pretty much useless\.  Should

Aha!

So, part of the problem here is that the contents list for "The
Matplotlib API" is full of names like "matplotlib_axes", which is a
module, and "matplotlib_artists", which documents a hierarchy of modules
inheriting from Artist--but by no means all such modules, since others,
like collections, stand alone. First, having all those "matplotlib_"
prefixes is distracting and makes it harder to find the information.

Agreed.

Second, the overall hierarchy is very inconsistent, with big categories
("artists") alongside details ("gridspec").

Agreed. I think we can greatly benefit from embracing categories and
other organizational concepts here and elsewhere such as the gallery
and large classes like axes. Are there good markup approaches we can
take to tag some docstrings to help sphinx organize things like this?

However, for the v1.0.x docs, I think the goal should be to get
whatever is missing filled in. Then merge that up to master (and add
animation_api docs). It would be in master where I think structural
changes to the docs should go.

I will have more time available Wednesday to work on this and I also
anticipate doing some of my wishlist work on mplot3d next week.

Ben Root

···

On Monday, May 16, 2011, Eric Firing <efiring@...229...> wrote:

On 05/16/2011 09:32 AM, Benjamin Root wrote:

On Mon, May 16, 2011 at 2:08 PM, Benjamin Root <ben.root@...553... >> <mailto:ben.root@…553…>> wrote:
On Mon, May 16, 2011 at 1:35 PM, Eric Firing <efiring@...229... >> <mailto:efiring@…229…>> wrote:
On 05/16/2011 06:56 AM, Benjamin Root wrote:
> On Tue, May 10, 2011 at 12:53 PM, John Hunter >> <jdh2358@...149... <mailto:jdh2358@…149…> >> > <mailto:jdh2358@…149…>> wrote:
> On Tue, May 10, 2011 at 12:48 PM, Benjamin Root >> <ben.root@...553... <mailto:ben.root@…553…> >> > <mailto:ben.root@…553… <mailto:ben.root@…854…>>> wrote:

13

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

Ben Root

···

On Monday, May 16, 2011, John Hunter <jdh2358@...149...> wrote:

On Mon, May 16, 2011 at 2:52 PM, Eric Firing <efiring@...229...> 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.

14

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

···

On Mon, May 16, 2011 at 5:28 PM, Benjamin Root <ben.root@…854…> wrote:

On Monday, May 16, 2011, John Hunter <jdh2358@…149…> wrote:

On Mon, May 16, 2011 at 2:52 PM, Eric Firing <efiring@…229…> 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

15

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

···

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

On Mon, May 16, 2011 at 5:28 PM, Benjamin Root <ben.root@…553…> wrote:

On Monday, May 16, 2011, John Hunter <jdh2358@…149…> wrote:

On Mon, May 16, 2011 at 2:52 PM, Eric Firing <efiring@…229…> 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

16

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

Yes!

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?

Sounds to me like this is a good time to merge it.

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

Glossary? I didn't even know there was one, so putting in a prominent link to it sounds like a good idea. I think that putting a FAQ link up front is also a good idea; maybe it will help remind us to keep expanding the FAQ when we keep seeing the same question on the mailing list.

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!

I have not yet tried to build from your branch, but based on descriptions and discussions, it should be a substantial improvement. Go ahead and push when you feel ready. Thank you for all the work.

Eric

···

On 05/20/2011 11:48 AM, Benjamin Root wrote:

Ben Root

17

Ben,

There is a tradeoff involved in adding more directives like ":term:" (which I was not even aware of): they make the html more clickable but they clutter the plain text. Even for html, having too many links can be distracting and reduce readability. So, use with caution. If it is easy to find the glossary, then I am not sure there is any net advantage in using "term" directives.

Eric

···

On 05/20/2011 11:48 AM, Benjamin Root wrote:

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.

18

I have started to try and merge my branch into the v1.0.x branch when I discovered some interesting oddities, and I am not 100% sure how I should go about resolving them. My very first commit in the docfix/smalltypos branch edited the doc/users/installing.rst document. However, it appears that on April 1, this file was removed from the repository and its information was consolidated over to the INSTALL file. However, even though I created my branch from the v1.0.x branch on April 30th, none of these changes are in my branch. Therefore, given how many other changes that were made to the documents, I wonder what other commits are missing.

Should I rebase my docfix/smalltypos branch with v1.0.x first or should I use the conflict merge process to let the installing.rst file be removed and make the changes I made over in INSTALL? Or maybe another idea that I haven’t thought of?

Ben Root

···

On Fri, May 20, 2011 at 6:58 PM, Eric Firing <efiring@…552…229…> wrote:

I have not yet tried to build from your branch, but based on

descriptions and discussions, it should be a substantial improvement. Go

ahead and push when you feel ready. Thank you for all the work.

19

I went ahead with the merge conflict procedure, and everything appear to be ok. I had also noticed a few additional mistakes in the INSTALL file currently in v1.0.x that I fixed as well. I will double-check the commit/merge before pushing it up.

I also noticed that the INSTALL doc on v1.0.x provided an equivalent command of apt-get build-dep for Fedora/RedHat users. I believe this information should also be included in the install_faq.rst document (because it only has the debian version). I will make that a separate commit.

Ben Root

···

On Sun, May 22, 2011 at 2:13 PM, Benjamin Root <ben.root@…854…> wrote:

On Fri, May 20, 2011 at 6:58 PM, Eric Firing <efiring@…229…> wrote:

I have not yet tried to build from your branch, but based on

descriptions and discussions, it should be a substantial improvement. Go

ahead and push when you feel ready. Thank you for all the work.

I have started to try and merge my branch into the v1.0.x branch when I discovered some interesting oddities, and I am not 100% sure how I should go about resolving them. My very first commit in the docfix/smalltypos branch edited the doc/users/installing.rst document. However, it appears that on April 1, this file was removed from the repository and its information was consolidated over to the INSTALL file. However, even though I created my branch from the v1.0.x branch on April 30th, none of these changes are in my branch. Therefore, given how many other changes that were made to the documents, I wonder what other commits are missing.

Should I rebase my docfix/smalltypos branch with v1.0.x first or should I use the conflict merge process to let the installing.rst file be removed and make the changes I made over in INSTALL? Or maybe another idea that I haven’t thought of?

Ben Root

20

Ben, a quick look at installing_faq.rst shows some anachronisms: references to installing obsolete versions. This is another worm barrel. Those anachronisms are not the only problems with the file--or with installation in general.

Eric

···

On 05/22/2011 10:07 AM, Benjamin Root wrote:

I went ahead with the merge conflict procedure, and everything appear to
be ok. I had also noticed a few additional mistakes in the INSTALL file
currently in v1.0.x that I fixed as well. I will double-check the
commit/merge before pushing it up.

I also noticed that the INSTALL doc on v1.0.x provided an equivalent
command of `apt-get build-dep` for Fedora/RedHat users. I believe this
information should also be included in the install_faq.rst document
(because it only has the debian version). I will make that a separate
commit.

Ben Root