[AstroPy] Documentation Guidelines

[Erik Tollerud]

To see all the docs actually rendered in sphinx (from Tom's repo), go
to http://eteq.github.com/astropy_doc_test/ - that compares the
formats suggested so far.

> 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.

Oh, I think we all agree with that - I was asking if "slightly harder
to read but still pretty easy" is an acceptable trade-off if the
sphinx docs look significantly better.

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

Do you have any sectioning in the pywcs format?  Some of the astropy
classes will no doubt be rather complex, and hence they will require
things like lists and "seealso" sections and references... I'm
concerned that if the format doesn't have any syntactic hints (that
sphinx will process to organize the doc), it will be difficult to read
for more elaborate docstrings.



On Tue, Jul 12, 2011 at 11:11 AM, Thomas Robitaille
<thomas.robitaille at gmail.com> wrote:
> 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
>>
> _______________________________________________
> AstroPy mailing list
> AstroPy at scipy.org
> http://mail.scipy.org/mailman/listinfo/astropy
>



-- 
Erik Tollerud