[Numpy-discussion] Finalising documentation guidelines for NumPy

Stefan van der Walt stefan@sun.ac...
Tue Jul 17 06:38:08 CDT 2007


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


More information about the Numpy-discussion mailing list