Re: future of mpl documentation

On Saturday 31 May 2008 4:14:39 pm Darren Dale wrote:
> On Saturday 31 May 2008 12:36:11 pm John Hunter wrote:
> > On Sat, May 31, 2008 at 9:19 AM, Darren Dale <darren.dale@...>
>
> wrote:
> > > I'll be working on converting docstrings to rest this weekend. Should
> > > any of this be done on the branch? Or should we just focus on the
> > > trunk?
> >
> > As far as I am concerned, the documentation effort is for the trunk.
>
> I would really prefer to concentrate on the trunk. There's enough work as
> it is.

I made some pretty good progress today. I found the source of that error that 
was causing sphinx to fail without a helpfull message, there was a ********* 
in the contour documentation. pyplot_api is about halfway converted, there 
are only 60 warnings reported by sphinx for pyplot.

I just realized, though, that I should probably be striving to conform with 
the standard that the numpy and scipy folks put together: 
http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and 
http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? I 
think I have been relying too heavily on tables for the keyword arguments.

Darren

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.

Re: future of mpl documentation

Hey folks,

I'm super excited about this, so I decided to give it a quick test run
with current trunk SVN.  Running ./make.py in the doc/ directory
worked for a while, and then stalled at:

Sphinx v0.3, building latex
trying to load pickled env... done
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
processing Matplotlib.tex... index users/index users/pyplot_tutorial
users/mathtext users/navigation_toolbar users/customizing
users/artists users/event_handling faq/index faq/installing_faq
faq/troubleshooting_faq faq/howto_faq devel/index devel/coding_guide
devel/documenting_mpl devel/add_new_projection api/index
api/artist_api api/pyplot_api
resolving references...
writing... Exception occurred:
  File "/home/fperez/usr/local/lib/python2.5/site-packages/Sphinx-0.3-py2.5.egg/sphinx/latexwriter.py",
line 479, in visit_entry
    raise NotImplementedError('Column or row spanning cells are '
NotImplementedError: Column or row spanning cells are not implemented.
The full traceback has been saved in /tmp/sphinx-err-l_Oadi.log, if
you want to report the issue to the author.
Please also report this if it was a user error, so that a better error
message can be provided next time.
Send reports to sphinx-dev@... Thanks!
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
 %&-line parsing enabled.
entering extended mode

Re: future of mpl documentation

On Sat, May 31, 2008 at 9:01 PM, Fernando Perez <fperez.net@...> wrote:

> I don't know if you are so in the middle of things that you'd rather
> not get bug reports on this for a while.  If that's the case I'll wait
> until the dust settles a bit.

Well, we definitely want our docs to build so we're happy to get the
feedback -- sometimes it's a simple matter of a dev forgetting to
commit a critical file.  I am getting this error too.  It appears to
be a bug in the pyplot docstrings -- Darren, perhaps you haven't
committed all you recent changes?  But if I remove entirely the pyplot
api doc which is causing this problem, I get lots of other errors
along the lines of those shown below.  Is this a latex or sphinxext
config error?

[8 <./pyplot_formatstr.png> <./pyplot_three.png>] [9] [10]
<pyplot_two_subplots.png, id=368, 578.16pt x 433.62pt>
<use pyplot_two_subplots.png> <use pyplot_two_subplots.png> [11 <./pyplot_two_s
ubplots.png>] <pyplot_text.png, id=375, 578.16pt x 433.62pt>
<use pyplot_text.png> <use pyplot_text.png> [12 <./pyplot_text.png>] [13]
[14]
Chapter 2.
[15] [16]
! Undefined control sequence.
<recently read> \mathbb

l.954 \end{tabulary}

?
! Undefined control sequence.

Re: future of mpl documentation

On Mon, May 26, 2008 at 1:50 PM, Tony Yu <tsyu80@...> wrote:

> I played around with the script, but in the process I ended up rewriting it
> a bunch. I'm sure I've violated come coding guidelines along the way; my
> apologies.

And I made several changes -- mainly to simplify the logo.  My wife
thought it looked busy, and she has better taste than I do,  so I
stripped it down a bunch and added the many small subplots as a
sidebar on the right.  Let me know what you think and don't be shy
about being critical despite Darren's kind sensitivities.  I don't
take pride in my graphic design abilities and so will happily make
changes

See http://matplotlib.sf.net for the new logo(s) and the attached for
the stripped down script.

JDH

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@...
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Re: future of mpl documentation

On Sat, May 31, 2008 at 3:19 PM, Darren Dale <darren.dale@...> wrote:

  Darren> I have to break here for the weekend, I'll be back monday afternoon.
  Darren> Leave some for me! (although I'll owe doughnut to whoever can fix the
  Darren> arrow docstring).

  John> I'll claim that doughnut.

  Darren> When was the last time you received one in the mail?

Well, I remember the last time quite clearly, when Perry sent me a
doughnut in the mail from Maryland to settle a "dollars-to doughnuts"
bet.  Unfortunately, I  can't remember the subject of the bet right
now (Perry?), though I kept the doughnut in my freezer, in the
addressed envelope, for many months as a souvenir.

JDH

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/

Re: future of mpl documentation

On Sat, May 31, 2008 at 7:50 PM, Darren Dale <darren.dale@...> wrote:

> I just realized, though, that I should probably be striving to conform with
> the standard that the numpy and scipy folks put together:
> http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and
> http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? I
> think I have been relying too heavily on tables for the keyword arguments.

I think that following their guidelines is a good idea for the most
part, but we needn't adhere to them religiously.  For one thing,
matplotlib uses *a lot* more keyword args than either numpy or scipy,
and what works for them for kwargs may not be best for us.  In
particular, if we use the format they suggest, I'm afraid our
docstrings will simply take up too much space.  For example, see
http://mentat.za.net/numpy/refguide/functions.xhtml#all-a-axis-none-out-none
.  What if we formatted all the Line2d kwargs that way?  It seems a
bit bloated in terms of vertical space for the number of kwargs we
need to handle, and so a ReST  table may in fact be better.

We want our documentation to be mostly consistent to aid the folks
trying to put together bits and pieces of documentation from several
projects to write in-house docs (which incorporate local docs) or
books, but I'm not sure we need our doc formatting to be entirely
consistent at the API level.

JDH

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.

Re: future of mpl documentation

On Saturday 31 May 2008 10:19:47 pm John Hunter wrote:
> On Sat, May 31, 2008 at 9:01 PM, Fernando Perez
<fperez.net@...> 
wrote:
> > I don't know if you are so in the middle of things that you'd rather
> > not get bug reports on this for a while.  If that's the case I'll wait
> > until the dust settles a bit.
>
> Well, we definitely want our docs to build so we're happy to get the
> feedback -- sometimes it's a simple matter of a dev forgetting to
> commit a critical file.  I am getting this error too.  It appears to
> be a bug in the pyplot docstrings -- Darren, perhaps you haven't
> committed all you recent changes?  

All my changes had already been committed. I had only been creating html 
(./make.py html) and it looks like some of the tables I have been creating 
dont agree with latex. I'll fix it tomorrow, but in the meantime, please just 
make html.  

> But if I remove entirely the pyplot 
> api doc which is causing this problem, I get lots of other errors
> along the lines of those shown below.  Is this a latex or sphinxext
> config error?

Not sure, I'll look into it on Sunday as well.

Cheers,
Darren

-------------------------------------------------------------------------

Re: future of mpl documentation

On May 31, 2008, at 10:30 PM, John Hunter wrote:
>
> And I made several changes -- mainly to simplify the logo.  My wife
> thought it looked busy, and she has better taste than I do,  so I
> stripped it down a bunch and added the many small subplots as a
> sidebar on the right.

I agree, the stripped down logo looks much better.

> Let me know what you think and don't be shy
> about being critical despite Darren's kind sensitivities.  I don't
> take pride in my graphic design abilities and so will happily make
> changes
>
> See http://matplotlib.sf.net for the new logo(s) and the attached for
> the stripped down script.

I like the new color scheme on the website. Since you asked for  
criticism, though, I'm not a fan of the blue "matplotlib" in the logo  
(on the website, the attached logo is actually different). I think  
black or a dark gray looks better (color=[0.2, 0.2, 0.2]). Or, if you  
prefer blue, something less like the default hyperlink color (e.g.  
color=[.1,.1,.5]). My 2 cents.

BTW, I noticed that website is a little old (pure HTML, no CSS). If  
you're ever interested in redesigning the website (nothing fancy,  
mainly just moving to CSS), I'd be happy to help out.

-Tony

Re: future of mpl documentation

On Sat, May 31, 2008 at 11:27 PM, Tony Yu <tsyu80@...> wrote:

> I like the new color scheme on the website. Since you asked for criticism,
> though, I'm not a fan of the blue "matplotlib" in the logo (on the website,
> the attached logo is actually different). I think black or a dark gray looks
> better (color=[0.2, 0.2, 0.2]). Or, if you prefer blue, something less like
> the default hyperlink color (e.g. color=[.1,.1,.5]). My 2 cents.

I agree -- I had already reverted to black (hit refresh).  But if you
think some other shade of dark gray or blue/gray is better let me
know.

> BTW, I noticed that website is a little old (pure HTML, no CSS). If you're
> ever interested in redesigning the website (nothing fancy, mainly just
> moving to CSS), I'd be happy to help out.

We're definitely interested.  Try checking out the htdocs svn
repository.  Admittedly we do things in our own special way (eg the
YAPTU template engine), but if we could improve the look-and-feel that
would be great.  None of us have any special powers in the
website-design department.  Even better, as part of our new trunk
documentation effort, we have moved to a sphinx based documentation
system (in the doc subdir of svn trunk).  If you could figure out a
way to hook custom CSSandr mpl figures/screenshots or any other snazzy
features into the base sphinx build system, that would be a big help
since we hope to jettison the somewhat anachronistic website build
system n the not-too-distant-future.

JDH

Re: Bug when embedding Matplotlib 0.91.2 in PyQt 4.4.2

>
> Hi Pierre,
>
> On Friday 30 May 2008 5:21:01 pm Pierre Raybaut wrote:
>   
>> > First, I would like to congratulate you for your work on Matplotlib. I
>> > am using Matplotlib widgets in all my current projects, embedded in PyQt
>> > graphical user interfaces.
>> >
>> > As you may know, PyQt 4.4.2 has been released a few days ago.
>> > And I found out a performance bug when embedding a Matplotlib 0.91.2
>> > canvas in a PyQt 4.4.2 object: the pan/zoom feature is very slow (with
>> > PyQt 4.3.3, and the exact same scripts, pan/zoom is real-time).
>>     
>
> Would it be possible to post some benchmarks, something a little more 
> concrete, like specifically what calls are taking the most time, and how they 
> compare for the different versions of PyQt?
>   

Yes of course, I will send the requested informations as soon as I can.
>   
>> > I am posting this in PyQt mailing-list too, but I guess that you could
>> > have more ideas on that matter (Matplotlib widgets may not be used very
>> > often in PyQt).
>>     
>
> Please don't do that. Its not fair to the people who volunteer their time on 
> open source projects to try to draw so many people into the problem before 
> the problem is understood.