On Dec 28, 2007 5:26 AM, Stefan van der Walt <stefan@sun.ac.za> wrote:
On Thu, Dec 27, 2007 at 09:27:09PM -0800, Jarrod Millman wrote:
> On Dec 27, 2007 7:42 PM, Travis E. Oliphant <oliphant@enthought.com> wrote:
> > Doc-day will start tomorrow (in about 12 hours).  It will be Friday for
> > much of America and be moving into Saturday for Europe and Asia.  Join
> > in on the irc.freenode.net  (channel scipy) to coordinate effort.  I
> > imaging people will be in an out.  I plan on being available in IRC from
> > about 9:30 am CST to 6:00 pm CST and then possibly later.
> >
> > If you are available at different times in different parts of the
> > world,  jump in and pick something to work on.
>
> Since this is our first doc-day, it will be fairly informal.  Travis
> is going to be trying to get some estimate of which packages need the
> most work.  But if there is some area of NumPy or SciPy you are
> familiar with, please go ahead and pitch in.  Here is the current
> NumPy/ SciPy coding standard including docstring standards:
> http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines

I have some questions regarding Travis' latest modifications to the
documentation guidelines:

The following section was removed, why?

"""
A reST-documented module should define::

 __docformat__ = 'restructuredtext en'

at the top level in accordance with `PEP 258
<http://www.python.org/dev/peps/pep-0258 >`__.  Note that the
``__docformat__`` variable in a package's ``__init__.py`` file does
not apply to objects defined in subpackages and submodules.
"""

We had a long discussion on the mailing list on the pros and cons of
"*Parameters*:" vs. "Parameters:".  I see now that it has been changed
to

 Parameters
 ----------
 
If we are going to avoid ReST and html definition lists, i.e.
 
Parameters: 
 
then we should probably avoid ReST and headings
 
Parameters
----------
 
because that will likely be moved about. In fact, we should probably throw ReST overboard if we are going to avoid ReST'isms. I personally think the underline is ugly (hi Travis), but I suppose that's beside the point. If we stay with ReST it would be nice to retain the links in the see also section.
 
I'm not at home at the moment, so I don't know how the new style is rendered by epydoc, or even if we are still going to use epydoc. If not, we should definitely decide on the structure of the docstrings and stick to it. With a bit more pain in the appearence, we could also format for doxygen, which is pretty standard and would also work for the C code. I suspect that's not going to fly, though ;)
 
Chuck