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