[SciPy-dev] Technology Previews and Sphinx Docstring Annotations
Tue Nov 4 17:48:25 CST 2008
Tue, 04 Nov 2008 18:16:41 -0500, Nathan Bell wrote:
> 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  is going to the right
direction, and the Python reference docs  are not bad in my opinion.
..  http://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html
Check the "Show source" link on the left sidebar.
..  eg. http://docs.python.org/library/datetime.html
More information about the Scipy-dev