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