Thread: [matplotlib-devel] Website needs love

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

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

On Tue, May 10, 2011 at 12:42 PM, Jason Grout
<jas...@cr...>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
>
>
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: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.

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

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
>

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

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

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

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

> Ben Root
>

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.

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 Fri, May 20, 2011 at 6:58 PM, Eric Firing <ef...@ha...> 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

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

>
>
> On Fri, May 20, 2011 at 6:58 PM, Eric Firing <ef...@ha...> 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
>
>
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 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

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 11:33 AM, Benjamin Root wrote:
>
>
> On Sun, May 22, 2011 at 4:11 PM, Eric Firing <ef...@ha...
> <mailto:ef...@ha...>> wrote:
>
>     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
>
>     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
>
>
> I'll double-check for that.  Note that I am merely moving my changes
> over to INSTALL, so whatever INSTALL has should be the final version.
> Below is the current diff between them.

Right.  It looks like INSTALL is a slightly fixed-up version of the 
now-deleted install.rst.  I was referring to install_faq.rst.  Maybe 
that (or large parts of it) should go away, and be replaced by a 
reference to INSTALL?

Eric

On 05/22/2011 05:33 PM, Benjamin Root wrote:
>
>
> On Sun, May 22, 2011 at 4:11 PM, Eric Firing <ef...@ha... 
> <mailto:ef...@ha...>> wrote:
>
>     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
>
>     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
>
>
> I'll double-check for that.  Note that I am merely moving my changes 
> over to INSTALL, so whatever INSTALL has should be the final version.  
> Below is the current diff between them.
>
> On a separate note, I think there might be some unspecified 
> requirements for building the documentation.  On my newly set up 
> Ubuntu machine, the build gets to the thumbnails stage and recognizes 
> that I have no thumbnails, and then the process goes to sleep.  Maybe 
> we have an error check missing somewhere?
Generating the thumbnails has no additional requirements (it uses 
matplotlib's image module to scale the images).  However, it may be a 
problem with multiprocessing -- the thumbnails are generated in parallel 
on multi-core machines.  I haven't had problems myself, but it seems 
multiprocessing doesn't always work in certain environments.

Can you do me a favor?  Can you edit gen_gallery.py and replace the line 
beginning with "pool.map" to just "map" and let me know if that resolves 
this issue?  If it does, perhaps we should not use multiprocessing here.

Mike

-- 
Michael Droettboom
Science Software Branch
Space Telescope Science Institute
Baltimore, Maryland, USA

On Mon, 23 May 2011 09:35:57 -0400, Michael Droettboom <md...@st...> wrote:
> Generating the thumbnails has no additional requirements (it uses 
> matplotlib's image module to scale the images).  However, it may be a 
> problem with multiprocessing -- the thumbnails are generated in parallel 
> on multi-core machines.  I haven't had problems myself, but it seems 
> multiprocessing doesn't always work in certain environments.
> 
> Can you do me a favor?  Can you edit gen_gallery.py and replace the line 
> beginning with "pool.map" to just "map" and let me know if that resolves 
> this issue?  If it does, perhaps we should not use multiprocessing here.
> 
Given this seems to be one of the longer stages of the build process,
I'd appreciate if if we identified and fixed the underlying problem and
not simply sweep it under the rug.

- Ben

On Mon, May 23, 2011 at 12:11 PM, Ben Gamari <bga...@gm...> wrote:

> On Mon, 23 May 2011 09:35:57 -0400, Michael Droettboom <md...@st...>
> wrote:
> > Generating the thumbnails has no additional requirements (it uses
> > matplotlib's image module to scale the images).  However, it may be a
> > problem with multiprocessing -- the thumbnails are generated in parallel
> > on multi-core machines.  I haven't had problems myself, but it seems
> > multiprocessing doesn't always work in certain environments.
> >
> > Can you do me a favor?  Can you edit gen_gallery.py and replace the line
> > beginning with "pool.map" to just "map" and let me know if that resolves
> > this issue?  If it does, perhaps we should not use multiprocessing here.
> >
> Given this seems to be one of the longer stages of the build process,
> I'd appreciate if if we identified and fixed the underlying problem and
> not simply sweep it under the rug.
>
> - Ben
>
>
Don't have a lot of time because I am on travel right now, but I think I
figured out the cause.  For whatever reason, there was some sort of missing
file error that caused the generation of the thumbnails to drop down to the
debugger prompt.  When within the multiprocessing pool, everything just
pauses, but nothing shows because the input is disconnected.  After a call
to clean, I was able to run the docs with and without "pool".

I hope that is a useful tip that could help figure out how to prevent a
unresponsive process.

Ben Root

On Sun, May 22, 2011 at 4:11 PM, Eric Firing <ef...@ha...> wrote:

> 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
>
> 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
>
>
I'll double-check for that.  Note that I am merely moving my changes over to
INSTALL, so whatever INSTALL has should be the final version.  Below is the
current diff between them.

On a separate note, I think there might be some unspecified requirements for
building the documentation.  On my newly set up Ubuntu machine, the build
gets to the thumbnails stage and recognizes that I have no thumbnails, and
then the process goes to sleep.  Maybe we have an error check missing
somewhere?

Ben Root


ben@tigger:~/Programs/matplotlib$ diff INSTALL doc/users/installing.rst
0a1,2
> .. _installing:
>
23c25
< Manually installing pre-built packages
---
> OK, so you want to do it the hard way?
81c83
< :ref:`install_osx_binaries`.
---
> ref:`install_osx_binaries`.
88,112d89
< Installing on Windows
< ---------------------
<
< If you don't already have python installed, you may want to consider
< using the enthought edition of python, which has scipy, numpy, and
< wxpython, plus a lot of other goodies, preinstalled - `Enthought
< Python <http://www.enthought.com/python>`_.  With the enthought
< edition of python + matplotlib installer, the following backends
< should work out of the box: agg, wx, wxagg, tkagg, ps, pdf and svg.
<
< For standard python installations, you will also need to install numpy
< in addition to the matplotlib installer.  On some systems you will
< also need to download msvcp71.dll library, which you can download from
< http://www.dll-files.com/dllindex/dll-files.shtml?msvcp71 or other
< sites.  You will need to unzip the archive and drag the dll into
< :file:`c:\windows\system32`.
<
< All of the GUI backends run on windows, but TkAgg is probably the
< best for interactive use from the standard python shell or ipython.
< The windows installer (:file:`*.exe`) on the download page contains all
the
< code you need to get up and running.  However, there are many
< examples that are not included in the windows installer.  If you
< want to try the many demos that come in the matplotlib src
< distribution, download the zip file and look in the examples subdir.
<
142,147d118
< If you have installed prerequisites to nonstandard places and need to
< inform matplotlib where they are, edit ``setupext.py`` and add the base
< dirs to the ``basedir`` dictionary entry for your ``sys.platform``.
< e.g., if the header to some required library is in
< ``/some/path/include/someheader.h``, put ``/some/path`` in the
< ``basedir`` list for your platform.
163,178d133
< .. note::
<
<     If you are on debian/ubuntu, you can get all the dependencies
<     required to build matplotlib with::
<
<       sudo apt-get build-dep python-matplotlib
<
<     This does not build matplotlib, but it does get the install the
<     build dependencies, which will make building from svn easy.
<
<     If you are on Fedora/RedHat, you can get all the dependencies
<     required to build matplotlib by first installing ``yum-builddep``
<     and then running::
<
<        su -c "yum-builddep python-matplotlib"
<
186c141
< libpng 1.2 (or later)
---
> libpng 1.1 (or later)
216a172,175
> :term:`wxpython` 2.6 or later
>     The python wrappers for the wx widgets library for use with the
>     WXAgg backend
>
219c178
<     WX or WXAgg backend
---
>     WX backend
242a202,203
>
>
246c207
< ===============
---
> ==================