doc warnings

Hi,

···

On Thu, 2008-07-24 at 13:08 -0700, matplotlib-devel-request@lists.sourceforge.net wrote:

WARNING: /home/jdhunter/dev/lib64/python2.5/site-packages/matplotlib/axes.py:docstring
of matplotlib.axes.Axes.acorr:36: (ERROR/3) Unexpected indentation.
WARNING: <autodoc>:0: (ERROR/3) Unexpected indentation.
WARNING: /home/jdhunter/dev/lib64/python2.5/site-packages/matplotlib/backend_bases.py:docstring
of
matplotlib.backend_bases.FigureCanvasBase.start_event_loop_default:15:
(WARNING/2) Literal block expected; none found.

I looked at my doc strings and as far as I can tell, they are identical
in format to other functions around them. What does this error mean?

Cheers,
David

--
**********************************
David M. Kaplan
Charge de Recherche 1
Institut de Recherche pour le Developpement
Centre de Recherche Halieutique Mediterraneenne et Tropicale
av. Jean Monnet
B.P. 171
34203 Sete cedex
France

Phone: +33 (0)4 99 57 32 27
Fax: +33 (0)4 99 57 32 95
http://www.ur097.ird.fr/team/dkaplan/index.html
**********************************

The problem is after the double colon in the following block::

        This function provides default event loop functionality based
        on time.sleep that is meant to be used until event loop
        functions for each of the GUI backends can be written. As
        such, it throws a deprecated warning.

        Call signature::

        start_event_loop_default(self,timeout=0)

you need to indent relative to the line containing the double colon, eg::

        Call signature::

            start_event_loop_default(self,timeout=0)

        This call blocks until a callback function triggers
        stop_event_loop() or *timeout* is reached. If *timeout* is
        <=0, never timeout.

I went ahead and committed this change.
JDH

···

On Fri, Jul 25, 2008 at 2:48 AM, David Kaplan <David.Kaplan@...622...> wrote:

Hi,

On Thu, 2008-07-24 at 13:08 -0700, > matplotlib-devel-request@lists.sourceforge.net wrote:

WARNING: /home/jdhunter/dev/lib64/python2.5/site-packages/matplotlib/axes.py:docstring
of matplotlib.axes.Axes.acorr:36: (ERROR/3) Unexpected indentation.
WARNING: <autodoc>:0: (ERROR/3) Unexpected indentation.
WARNING: /home/jdhunter/dev/lib64/python2.5/site-packages/matplotlib/backend_bases.py:docstring
of
matplotlib.backend_bases.FigureCanvasBase.start_event_loop_default:15:
(WARNING/2) Literal block expected; none found.

I looked at my doc strings and as far as I can tell, they are identical
in format to other functions around them. What does this error mean?

David, I cleaned up a few more of these warnings. I notice on most of
the functions you added to cbook, you added call signature lines, in
many cases where they are not needed. I want to try and clarify where
they are needed. If your function uses *args or **kwargs that pass
through, you want to give the user some idea what those are. This is
most important in pylab, which pass the args and kwargs through to the
equivalent Axes method. Since the pylab docstring just reads *args,
**kwargs, we use the Axes method of the same name to show the call
signature. In general, you do not need to add these, especially if
your function declaration explicitly lists the args and keyword args,
so I have removed most of these.

Also, I would rather not put the geometry functions in cbook, eg
distances_along_curve and path_length and friends. Perhaps we should
have some sort of geometry module where all these things live (there
are some in mlab as well) but barring that I would rather have
math/geometry stuff in mlab and general purpose helpers in cbook.
Let's move all those before the release so we don't have to worry
about API breakage later.

JDH

···

On Fri, Jul 25, 2008 at 10:09 AM, John Hunter <jdh2358@...149...> wrote:

The problem is after the double colon in the following block::

Hi,

Also, I would rather not put the geometry functions in cbook, eg
distances_along_curve and path_length and friends. Perhaps we should
have some sort of geometry module where all these things live (there
are some in mlab as well) but barring that I would rather have
math/geometry stuff in mlab and general purpose helpers in cbook.
Let's move all those before the release so we don't have to worry
about API breakage later.

I started looking at this reorganization, but it seems to me that mlab
already has a number of functions that don't seem to have much to do
with its initial purpose - matlab compatibility. This was pretty
confusing for me when I initially started using matplotlib as the mlab
namespace was a mix of familiar and unfamiliar.

I decided instead to group several functions into a "numerical_methods"
module that includes most of my new cbook functions as well as some
linear interpolation and polygon stuff from mlab. I moved isvector to
mlab since this really is an imitation of a matlab function of the same
name. I have propagated these changes through to other functions in
matplotlib that use them and added remarks in CHANGELOG and API_CHANGES.

As these changes may be debatable, I haven't committed them. Instead, I
am attaching a patchset. I probably won't check email this weekend, so
I will let the powers that be decide what to do with this.

Along the way, I noticed these is some duplication in the examples
directory between pylab_examples and mpl_examples.

Cheers,
David

numerical_methods_reorganization.patch (27.8 KB)

···

On Fri, 2008-07-25 at 12:43 -0500, John Hunter wrote:

JDH

--
**********************************
David M. Kaplan
Charge de Recherche 1
Institut de Recherche pour le Developpement
Centre de Recherche Halieutique Mediterraneenne et Tropicale
av. Jean Monnet
B.P. 171
34203 Sete cedex
France

Phone: +33 (0)4 99 57 32 27
Fax: +33 (0)4 99 57 32 95
http://www.ur097.ird.fr/team/dkaplan/index.html
**********************************

I started looking at this reorganization, but it seems to me that mlab
already has a number of functions that don't seem to have much to do
with its initial purpose - matlab compatibility. This was pretty
confusing for me when I initially started using matplotlib as the mlab
namespace was a mix of familiar and unfamiliar.

I'm not too keen on having general math in one module and matlab
compatible math in another, in part because this will be confusing to
folks not too familiar with matlab, and as time passes (I never use it
anymore) that is starting to include me. I think we could avoid some
confusion by simply fixing the docstring in mlab. So I'd rather put
all the math stuff in mlab, and possibly pull the geometry specific
stuff into a separate module.

As these changes may be debatable, I haven't committed them. Instead, I
am attaching a patchset. I probably won't check email this weekend, so
I will let the powers that be decide what to do with this.

OK, thanks. I will try nd look at this over the weekend.

Along the way, I noticed these is some duplication in the examples
directory between pylab_examples and mpl_examples.

mpl_examples is a sym link we use for the rest doc builds so the
examples can be included w/o the doc writer needing to know the path
structure. That way if we want to reorganize later, we can update the
symlink rather than all the docs

jdhunter@...606...:mpl> ls -ld lib/mpl_examples
lrwxrwxrwx 1 jdhunter jdhunter 11 2008-07-25 20:37 lib/mpl_examples ->
../examples
jdhunter@...606...:mpl> ls -ld doc/mpl_examples
lrwxrwxrwx 1 jdhunter jdhunter 12 2008-06-02 07:31 doc/mpl_examples ->
../examples/

JDH

···

On Sat, Jul 26, 2008 at 7:19 AM, David M. Kaplan <David.Kaplan@...622...> wrote:

John Hunter wrote:

I'm not too keen on having general math in one module and matlab
compatible math in another, in part because this will be confusing to
folks not too familiar with matlab, and as time passes (I never use it
anymore) that is starting to include me. I think we could avoid some
confusion by simply fixing the docstring in mlab. So I'd rather put
all the math stuff in mlab, and possibly pull the geometry specific
stuff into a separate module.
  

FWIW, there are also a number of C++ geometry functions in _path.cpp that perhaps should be considered in this reorg.

(But I'm just catching up on thousands of e-mails today, so I won't comment on the reorg itself <wink>)

Cheers,
Mike

···

--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA