[SciPy-dev] [Matplotlib-users] [matplotlib-devel] Unifying numpy, scipy, and matplotlib docstring formats

[David Huard]

In the previous docstring thread, there has been a lot of lively discussion
about whether or not we should follow reST syntax for the docstrings.
Briefly put, the arguments were that some of the markup is ugly, but then
using the markup gives you access to packages processing reST to generate
nice looking output for api documentation. At the time, the concensus was
that we should follow the reST syntax, with an additional role (:math:) and
directive (.. math::)  to process latex formulas. However, I get the feeling
that there are many people who feel that this tradeoff between console
readability and ease of post-processing is disapointing (I am one of those),
and that there should be a way to get the best of both worlds. I submitted
my concern for the lack of a clear documentation standard to the reST dev
ML, but didn't get much feedback.

Jens ( a docutils dev) and Alan suggested that plugin support for docutils
was in the air, but a lack of man power delayed its implementation. I don't
how far we could go with this idea, but maybe it would be possible to write
a plugin for docutils to specifically parse docstrings. The plugin would be
loaded by other apps making use of docutils, so we wouldn't have to hack the
epydoc parser or any third party application using reST. By restricting the
application of the plugins to docstrings (and not all the other stuff reST
is used for), we could probably remove some of the terseness of the markup,
and get a result that looks good on console and in print, without having to
manage patches for docutils, epydoc and all the others tools that are out
there.

For example, the plugin could enable directives to be written as

DIRECTIVE:
    blablabla
(capitalized word + : + indented block) as in Keir's proposal,

instead of
.. directive::
    blablabla

which would allow us to get rid of :Parameters: and friends.

Cheers,

David

2007/2/15, Christopher Barker <Chris.Barker at noaa.gov>:
>
> Keir Mierle wrote:
> > I do not want to descend into a huge, time wasting discussion of this
> > which is not productive.
>
> Well, it's been said before, and this isn't really the place for it, but
> it's quite critical to your project. Don't let any of this get in the
> way of improving docs strings, however!
> > Note that I am not suggesting a recursive import of submodules.
>
> What you appeared to support was that all of the matplotlib, numpy and
> scipy base namespaces be merged, and they should all be merged into the
> main namespace.
>
> >> import matplotlib as plot
> >> import numpy as N
> >> import Scipy.whatever as whatever.
> >
> > UGH. See, this is my issue. When I read someone else's code, they always
> > chose a different convention.
>
> Good point, that is a bit of a pain. It would certainly be a good idea
> to standardize at least these three, and have them be imported by
> default in your environment (though I'm not sure about scipy -- numpy
> and matplotlib would be good)
>
> > If we define the official way to use pylab as 'from pylab import *',
> > then these problems vanish.
>
> and others arise. One is that you then have to make sure you don't' get
> any name clashes you don't want, so you end up with arange, so it won't
> clash with range. etc.
>
> > Note that we must be *very* careful to export only
> > exactly the names which should be exported;
>
> Then how do you get the others? "import *" and "import pylab"?
>
> > Because it is always the case
> > that I use numpy and pylab together.
>
> I use numpy every day without pylab. And I use pylab occasionally
> without numpy, it accepts regular old lists for quick hacking.
>
> This is a key point -- if all anyone does is use your mega-pylab, then
> you may be right, but let's not cripple people. Let them start using
> PyLab for matlab-like quickie coding, then decide to write a real app,
> and be able to start using wxPython without learning a bunch of new
> stuff, and having namespaces clash.
>
> > Other non-core modules should be
> > treated as usual, where it is at the author's discretion for how to
> import them.
>
> Everyone's idea of non-core is different
>
> Even if you insist on joining numpy and plotting namespaces (they are
> both too big at the moment, if you ask me), please tell people to import
> it as:
>
> import pylab
>
> I think a consensus is building in the python community that you should
> NEVER use import *!
>
> some history:
>
> wxPython used to be commonly used as:
>
> from wxpython import *
>
> And the names were all: wxSomeName.
>
> A few years back, the names were all changed to remove the wx, and we
> now all do:
>
> import wx
> this = wx.SomeName(...)
>
> Numeric was designed to be used with "import *". Now many of the old
> Numeric functions are available as numpy methods, and more and more
> people are using some variation of:
>
> import numpy as N
>
> and fewer are using "import *"
>
> Does anyone else have any other examples?
>
> One more reason: more IDEs are providing auto-completion and module
> browsers. Smaller, more hierarchical namespaces are much better for
> this. I know if I'm looking for a number crunching or a plotting
> function -- make it easier to find them.
>
> > I think Scott Meyer, a C++ luminary, said it best [1] when this heinous
> > fragment of his code was posted in comp.lang.c++.moderated
>
> namespaces are a new add-on to C++ -- it will be a good while before
> they are used right there!
>
> > This is only for the core functionality. The scipy/numpy/matplotlib core
> > API becomes similar in importance to Python's __builtins__ for the PyLab
> > environment.
>
> >>> len(dir(__builtins__))
> 129
> >>> len(dir(pylab))
> 432
>
> and __builtins__ is too big as it is. -- 31 of those are Exceptions,
> they should have their own namespace, if you ask me. Would it be that
> much harder to type
>
> except Errors.Type:
>
> than
>
> except TypeError:
>
> > I argue that Python's __builtins__ should be equivalent to PyLab's from
> > pylab
> > import *, and that e.g. import sys corresponds to import linalg.
>
> But then you have __builtins__ and pylab in the same namespace!
>
> > Perhaps non-interactively; when using the system interactively the
> MATLAB
> > interface is by far the best way to go. If someone proposes an oo
> interface
> > which is as fast to type and as easy to understand as the MATLAB
> interface
> > (i.e. to demo to my friends who came over to see what I'm talking about
> > when I
> > say that PyLab is great) then I'm all ears.
>
> Look for my (and other) posts about this for more detail, but a few
> points:
>
> 1) Don't break long-term productivity/useability so that the quicky
> demos are more impressive. Python's real strength over tools like Matlab
> shows up when projects get bigger.
>
> 2) There is nothing about an OO interface that is inherently harder to
> use, or even more typing, except perhaps a few extra dots.
>
> 3) There is some work to be done to bring the matplotlib OO interface up
> to its potential for interactive use, particularly the docs!
>
> > Note that this discussion is early! I am waaaay not here yet; first step
> > is to fix the docstrings.
>
> Yes, enough said for now -- and I really appreciate your efforts to
> clean up the docstrings.
>
> -Chris
>
>
> --
> Christopher Barker, Ph.D.
> Oceanographer
>
> Emergency Response Division
> NOAA/NOS/OR&R            (206) 526-6959   voice
> 7600 Sand Point Way NE   (206) 526-6329   fax
> Seattle, WA  98115       (206) 526-6317   main reception
>
> Chris.Barker at noaa.gov
>
> -------------------------------------------------------------------------
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to share
> your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> Matplotlib-users mailing list
> Matplotlib-users at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/matplotlib-users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20070215/1cc2f963/attachment.html>