[SciPy-dev] New coding style (docstrings) : question

[Alan G Isaac]

On Mon, 06 Aug 2007, dmitrey apparently wrote:
> I try to rewrite scipy.optimize docstrings (as well as openopt ones) in 
> new docstrings standard. 
> (it was assigned to my GSoC milestones)
> So please take a look at the example below - is all correct? 

I will add to Anne's comments.

1. Rely more heavily on the epydoc documentation.  Be sure
to run epydoc and see what you get: is it right?
(Actually, your example is pretty self-contained, so you
can just run rst2html.py on it first, to make sure it is
valide reST.)

2. In reST, you need an empty line before a field list:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists

3. You do not need an empty line between a field name and
the field body.

4. You are mixing stuff together arbitrarily in the field
body.  Use definition lists:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists
Especially: it is the classifier that is optional, not the definition.

5. I forget whether the OtherParameters field is implemented
in epdoc yet ... ?  May be "forthcoming".  You should be
able to leave it anyway ...

6. Do not add indentation for the text block after your
section headers (e.g., your Notes section).

hth,
Alan Isaac

PS A working example based on your post follows ...

Section
-------
No blank line needed after section
(but it looks better).

Blank line is needed before field list.

:field1:

        body1

:field2: body2

:Returns: (xopt, {fopt, iter, funcalls, warnflag})

  xopt : ndarray
    minimizer of function
  fopt : number
    value of function at minimum: fopt = func(xopt)
  iter : number
    number of iterations
  funcalls : number
    number of function calls
  warnflag : number
    Integer warning flag:
          1 : 'Maximum number of function evaluations.'
          2 : 'Maximum number of iterations.'
  allvecs : list
    a list of solutions at each iteration