Stefan van der Walt 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. """

I don't see the point in every file having a __docformat__ line, when our documentaion formatting tool should already know the standard we are using is. It's just more cruft. Besides the PEP was rejected, so I don't know why we should be following it. We obviously need a pre-processor to map our files to epydoc, so let's do that instead of contorting docstrings into a format demanded by the tool. The tool is a "tool" for us to use not be chained by.

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?).

In my mind, the rationale trumps the "impracticality" especially since epydoc still produces readable output. It is only the formatting that is not pretty-printed (although it doesn't look bad there either). So, AFAIK, nothing is actually broken (except a little HTML formatting on output of epydoc). But, now the docstrings don't look crufty to my eyes. Basically, the problem is that I *really* don't like the *Parameters*: thing and all the indentation that takes place inside of docstrings to satisfy epydoc. It is also inconsistent with the docstring standard that Enthought uses for the ETS tools suite. It was really hard for me to start writing docstrings that followed that pattern. It seems better to have docstrings than to have them fit into an epydoc_-defined pattern. I'm sorry if I made changes unilaterally. I didn't think there would be much concern as long as docstrings were moving forward. -Travis