[SciPy-dev] Technology Previews and Sphinx Docstring Annotations

[Pauli Virtanen]

Tue, 04 Nov 2008 18:16:41 -0500, Nathan Bell wrote:
[clip]
> I'd argue that scipy.spatial should exist in SciPy 0.7 so people
> actually use the thing.  A disclaimer in the docstring is sufficient
> warning.  Those that ignore the warning are still better off than they
> would have been without the code in the first place.

If this is not enough, it could also be possible to issue a FutureWarning 
on module import. Obnoxious, yes, but hard to miss. But I believe that 
serious users would anyway read the documentation or docstrings.


Which brings me to a point: would the authors of spatial be willing to 
write some documentation for their module, in addition to docstrings, now 
that we have some infrastructure in place for that? Basically, a page 
that groups the contents of the module logically and gives some brief 
background, defines concepts, and maybe shows some small examples would 
come handy for future users. Probably anything is improvement over an 
autogenerated list of classes and functions.

Unfortunately, the current Sphinx-generated Scipy docs are IMO *not* good 
examples how to do things right. This [1] is going to the right 
direction, and the Python reference docs [2] are not bad in my opinion.

.. [1] http://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html
   Check the "Show source" link on the left sidebar.

.. [2] eg. http://docs.python.org/library/datetime.html

-- 
Pauli Virtanen