[Numpy-discussion] [SciPy-dev] Doc-day
Stefan van der Walt
Fri Dec 28 05:26:17 CST 2007
On Thu, Dec 27, 2007 at 09:27:09PM -0800, Jarrod Millman wrote:
> On Dec 27, 2007 7:42 PM, Travis E. Oliphant <email@example.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:
I have some questions regarding Travis' latest modifications to the
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
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
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?).
More information about the Numpy-discussion