[SciPy-dev] Docstrings: scipy.linalg, scipy.integrate.ode, scipy.integrate.odepack

[Pauli Virtanen]

Hi all,

During the last doc-day, I did some ReSTful cleaning up of the
docstrings in scipy.linalg, and polished up scipy.integrate a bit.

I put the patches to Trac, Scipy tickets #596 and #597. Review is
appreciated, although I attempted to be careful.

There's also Epydoc-generated output at
http://www.iki.fi/pav/tmp/scipy/doc/index.html if you want to check what
the final result looks like. Unfortunately, not all of it is well-formed
ReST, so I (or someone) needs to look at fixing the markup a bit later.
Also, the default Epydoc stylesheet is a bit difficult for the eyes
here.

Without RST formatting: http://www.iki.fi/pav/tmp/scipy/scipy-part.html

Some questions popped up when writing this:

- Where to put documentation that concerns whole modules, eg.
  scipy.integrate.ode (currently in the module docstring) or
  scipy.integrate.quadpack (currently printed by quad_explain())?

  Typically these submodule docstrings in scipy are not easily
  accessible, as module contents are imported via "from xxx import *".
  Should they be appended to the main module's docstring?

- Should there be "official" epydoc-generated API documentation for
  Scipy somewhere?

- Grouping related parameters together makes sense sometimes:
  
  minx : float
  maxx : float
      Specify that x must lie in the range [minx, maxx]
  
  However, this is not valid ReST, because in a description list,
  each entry must have its own separate description. What to do?

- Epydoc generates lots of pages that are of no interest to the
  end-user. How to improve the situation?


.. #596 http://scipy.org/scipy/scipy/attachment/ticket/596/scipy-linalg-doc.patch
.. #597 http://scipy.org/scipy/scipy/attachment/ticket/597/scipy-integrate-ode-odepack-doc.patch

-- 
Pauli Virtanen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: Digitaalisesti allekirjoitettu viestin osa
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20080129/b5ea98bc/attachment.sig>