[Numpy-discussion] [SciPy-dev] Doc-day

[Charles R Harris]

On Dec 28, 2007 5:26 AM, Stefan van der Walt <stefan at 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 at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20071229/e5edb5fa/attachment.html>