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

[Stefan van der Walt]

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
  ----------

Is this still recognised as a list?

I noted that the examples are now no longer indented: does ReST allow this?


Note that building the example documentation, `epydoc example.py`, now
warns:

File /tmp/example.py, line 19, in example.foo
   Warning: Line 24: Wrong underline character for heading.
   Warning: Lines 27, 30, 32, 37, 39, 41, 43, 48, 50: Improper paragraph indentation.
   

While I understand the rationale behind

  "The guiding principle is that human readers of the text itself are
  given precedence over contorting the docstring so that epydoc_
  produces nice output."

I think that it would be impractical to break compatibility with the
only documentation builder we currently have (unless there are others
I am unaware of?).

Regards
Stéfan