[AstroPy] Documentation Guidelines

Mark Sienkiewicz sienkiew at stsci.edu
Tue Jul 12 15:26:03 EDT 2011

On 7/12/11 2:11 PM, Thomas Robitaille wrote:
> I've added this to the options discussed so far shown at
> https://github.com/astrofrog/astropy_doc_test

I thought that file is supposed to be numpydoc format.  Perhaps I am 

The point stands, though, that we don't need a particularly cluttered 
format to make the sphinx docs look reasonable.


> Cheers,
> Tom
> On 12 July 2011 14:00, Mark Sienkiewicz<sienkiew at stsci.edu>  wrote:
>>> 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.
>> _______________________________________________
>> AstroPy mailing list
>> AstroPy at scipy.org
>> http://mail.scipy.org/mailman/listinfo/astropy

More information about the AstroPy mailing list