[AstroPy] Documentation Guidelines

Mark Sienkiewicz sienkiew at stsci.edu
Tue Jul 12 14:00:33 EDT 2011


> I agree this is a bit more cumbersome to read, but it produces (at
> least, to my eye) much prettier sphinx APIs if you use it with
> autodoc/autosummary.  So I guess the question is: do we want the
> docstrings as they appear with ipython's "?" or help() to be
> prioritized over the sphinx output, vice-versa, or what?


I think help() should produce useful output.  I also think a programmer 
who is reading the source code for the function should be able to read 
the docstring directly in the source code.

Fortunately, I don't think we need to make a compromise.  Here is an 
example:

https://trac6.assembla.com/astrolib/browser/trunk/pywcs/lib/pywcs/pywcs.py#L126

http://www.astrolib.org/docs/development/html/pywcs/api_wcs.html#wcs

If that is good enough, then we don't need to consider more complicated 
markup in the docstring.





More information about the AstroPy mailing list