[AstroPy] Documentation Guidelines

[Thomas Robitaille]

I've added this to the options discussed so far shown at
https://github.com/astrofrog/astropy_doc_test

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
>