[Numpy-discussion] Finalising documentation guidelines for NumPy

2007-07-17 Thread Stefan van der Walt 
Hi all,

In May this year, Charles Harris posted to this mailing list

http://thread.gmane.org/gmane.comp.python.numeric.general/15381/focus=15407

discussing some shortcomings of the current NumPy (and hence SciPy)
documentation standard

http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/doc/HOWTO_DOCUMENT.txt

Since we are in the process of slowly migrating all documentation to
the new standard, it is worth revisiting the issue one last time,
before we put in any more effort.

We need a format which

- parses without errors in epydoc
- generates easily readable output and
- places sections in a pre-determined order

We also need to design a default style sheet, to aid the production of
uniform documentation.

At least the following changes are needed to the current standard:

1) In the parameters section,

   var1 : type
   Description.

   is parsed correctly but

   var1 :
   Description.

   breaks.  This can be fixed either by omitting the colon after
   'var1' in the second case, or by slightly modifying epydoc's output.

2) In the SeeAlso section, variables should be surrounded by `` to
   link to their relevant docstrings, i.e.

   :SeeAlso:
 - otherfunc : relationship to thisfunc.

   changes to

   :SeeAlso:
 - `otherfunc` : relationship to thisfunc.

According to a post in the thread mentioned above, epydoc also
permutes the sections in such a way that Notes and Examples appear in
the wrong places.  As far as I can tell, this is an epydoc issue,
which we should take up with Ed Loper.

If you have any information that could help us finalise the
specification, or would like to share your opinion, I'd be glad to
hear it.

Regards
Stéfan
___
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://projects.scipy.org/mailman/listinfo/numpy-discussion

Re: [Numpy-discussion] Finalising documentation guidelines for NumPy

2007-07-17 Thread Alan G Isaac 
On Tue, 17 Jul 2007, Stefan van der Walt apparently wrote:
var1 :
Description.
breaks.  This can be fixed either by omitting the colon after
'var1' in the second case, or by slightly modifying epydoc's output.

It breaks semantically too, no?
(The colon is a separator, separating the variable name from its type.)

By the way,
Are you referring to a particular document?  I see the 
following document
http://projects.scipy.org/scipy/numpy/wiki/DocstringStandards
which points to the detailed document.
http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/doc/HOWTO_DOCUMENT.txt
The detailed document seems the place to add your changes.
(Note that the renderred version is unavailable:
http://projects.scipy.org/scipy/numpy/wiki/HowToDocument)

Cheers,
Alan Isaac




___
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://projects.scipy.org/mailman/listinfo/numpy-discussion