[AstroPy] Python documentation (was IDL to Python Switchers Guide)

[Erik Tollerud]

I would say it makes sense to have a single wiki that everyone is
encouraged to use - in contrast to the software hosting, a wiki can be
much more flexible standards-wise, but its more important that the
information all be easily reachable from one place.

But I do think it makes more sense to have that wiki be wherever the
software repository ends up, rather than necessarily the
scipy/astrolib site. The one that probably wins out content-wise is
the one that the main package-builders actually contribute to, and
putting it in the same place (ideally, with an individual wiki tied to
each individual project's source, like bitbucket or trac does).  Also,
I personally think the astropython.org and astrobetter.com are a bit
better-looking and easier to use than the scipy/astrolib site... and
the possibility to alter such things rather than being locked into the
scipy design scheme is a plus.


> Yes, there's some truth to that. Those sections could be more inviting
> or informative in general. I suspect that may have been one factor in
> people deciding to host their own libraries rather than contributing
> to AstroLib, though no-one here has said so. However, it's actually
> the WHOLE of scipy.org that's a wiki (I even just did a minor edit on
> the front page...).
>
> I think there's no reason not to put user documentation on the same
> pages; there just isn't any there yet.

Well, I think a wiki is definitely *not* the place for actual
documentation at the developer level.  In Python, that is much easier
done within the source code itself (and/or with external files in the
source tree) by way of sphinx.  I know that was actually a reason why
I couldn't make headway in astrolib when I first looked at it - the
documentation at the developer level was difficult to follow.
User-level tutorials, overviews, and guides (like the switching guide)
are much better suited for the wiki, though, as they are more
loosely-coupled to the source code and don't have to be tied to a
particular project.

Then again, we may be talking about different things regarding
"developer" and "user."   In astronomy, lots of "users" will be
writing scripts that dig pretty deeply into what one might think of as
"developer" territory, so I'm not clear on where the line is...




-- 
Erik Tollerud