matplotlib-devel Mailing List for matplotlib

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

On Monday, May 16, 2011, Eric Firing <ef...@ha...> wrote:
> On 05/16/2011 09:32 AM, Benjamin Root wrote:
>>
>>
>> On Mon, May 16, 2011 at 2:08 PM, Benjamin Root <ben...@ou...
>> <mailto:ben...@ou...>> wrote:
>>
>>
>>
>>   On Mon, May 16, 2011 at 1:35 PM, Eric Firing <ef...@ha...
>>   <mailto:ef...@ha...>> wrote:
>>
>>     On 05/16/2011 06:56 AM, Benjamin Root wrote:
>>     >
>>     >
>>     > On Tue, May 10, 2011 at 12:53 PM, John Hunter
>>     <jd...@gm... <mailto:jd...@gm...>
>>     > <mailto:jd...@gm... <mailto:jd...@gm...>>> wrote:
>>     >
>>     >
>>     >
>>     >   On Tue, May 10, 2011 at 12:48 PM, Benjamin Root
>>     <ben...@ou... <mailto:ben...@ou...>
>>     > <mailto:ben...@ou... <mailto:ben...@ou...>>> 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
>> 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 05/16/2011 09:32 AM, Benjamin Root wrote:
>
>
> On Mon, May 16, 2011 at 2:08 PM, Benjamin Root <ben...@ou...
> <mailto:ben...@ou...>> wrote:
>
>
>
> On Mon, May 16, 2011 at 1:35 PM, Eric Firing <ef...@ha...
> <mailto:ef...@ha...>> wrote:
>
> On 05/16/2011 06:56 AM, Benjamin Root wrote:
> >
> >
> > On Tue, May 10, 2011 at 12:53 PM, John Hunter
> <jd...@gm... <mailto:jd...@gm...>
> > <mailto:jd...@gm... <mailto:jd...@gm...>>> wrote:
> >
> >
> >
> > On Tue, May 10, 2011 at 12:48 PM, Benjamin Root
> <ben...@ou... <mailto:ben...@ou...>
> > <mailto:ben...@ou... <mailto:ben...@ou...>>> 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
>
>
>
> 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
>
> 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
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

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.

On 05/16/2011 09:08 AM, Benjamin Root wrote:
>
>
> On Mon, May 16, 2011 at 1:35 PM, Eric Firing <ef...@ha...
> <mailto:ef...@ha...>> wrote:
>
> On 05/16/2011 06:56 AM, Benjamin Root wrote:
> >
> >
> > On Tue, May 10, 2011 at 12:53 PM, John Hunter <jd...@gm...
> <mailto:jd...@gm...>
> > <mailto:jd...@gm... <mailto:jd...@gm...>>> wrote:
> >
> >
> >
> > On Tue, May 10, 2011 at 12:48 PM, Benjamin Root
> <ben...@ou... <mailto:ben...@ou...>
> > <mailto:ben...@ou... <mailto:ben...@ou...>>> 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
>

On Mon, May 16, 2011 at 2:08 PM, Benjamin Root <ben...@ou...> wrote:
>
>
> On Mon, May 16, 2011 at 1:35 PM, Eric Firing <ef...@ha...> wrote:
>
>> On 05/16/2011 06:56 AM, Benjamin Root wrote:
>> >
>> >
>> > On Tue, May 10, 2011 at 12:53 PM, John Hunter <jd...@gm...
>> > <mailto:jd...@gm...>> wrote:
>> >
>> >
>> >
>> > On Tue, May 10, 2011 at 12:48 PM, Benjamin Root <ben...@ou...
>> > <mailto:ben...@ou...>> 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
>
>
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 1:35 PM, Eric Firing <ef...@ha...> wrote:
> On 05/16/2011 06:56 AM, Benjamin Root wrote:
> >
> >
> > On Tue, May 10, 2011 at 12:53 PM, John Hunter <jd...@gm...
> > <mailto:jd...@gm...>> wrote:
> >
> >
> >
> > On Tue, May 10, 2011 at 12:48 PM, Benjamin Root <ben...@ou...
> > <mailto:ben...@ou...>> 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

On 05/16/2011 06:56 AM, Benjamin Root wrote:
>
>
> On Tue, May 10, 2011 at 12:53 PM, John Hunter <jd...@gm...
> <mailto:jd...@gm...>> wrote:
>
>
>
> On Tue, May 10, 2011 at 12:48 PM, Benjamin Root <ben...@ou...
> <mailto:ben...@ou...>> 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
>
> Ben Root
>

Oops. I don't think we intend to drop support for Python 2.4 just yet. 
I forgot the with statement was so recent. I will revert this.
Cheers,
Mike
On 05/16/2011 01:14 PM, Benjamin Root wrote:
> I just noticed that some recent commits included the use of the 
> (somewhat) new 'with' construct. Are we officially dropping support 
> for python 2.4 in the master branch? If so, what other features could 
> we now utilize that were introduced in 2.5?
>
> 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
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> 
-- 
Michael Droettboom
Science Software Branch
Space Telescope Science Institute
Baltimore, Maryland, USA

I just noticed that some recent commits included the use of the (somewhat)
new 'with' construct. Are we officially dropping support for python 2.4 in
the master branch? If so, what other features could we now utilize that
were introduced in 2.5?
Ben Root

On Tue, May 10, 2011 at 12:53 PM, John Hunter <jd...@gm...> wrote:
>
>
> On Tue, May 10, 2011 at 12:48 PM, Benjamin Root <ben...@ou...> 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 Root