Repository navigation
Documentation re-organization/homogenization #162
Description
The current Sphinx documentation needs to be improved to make it more homogeneous (since a lot of the current docs were pulled in from existing projects). In a lot of cases, the import statements could be improved, e.g.
>>> import astropy.io.fits
>>> hdulist = astropy.io.fits.open('input.fits')
could be better written as:
>>> from astropy.io import fits
>>> hdulist = fits.open('input.fits')
Activity
astrofrog commentedon Apr 3, 2012
With #115 merged and #187 about to be (thanks @eteq!), do we want to now discuss how to lay out the documentation consistently across sub-packages? This is probably one of the more major things to be dealt with before 0.1.0. I think we just need to lay out some guidelines for documenting sub-packages, and have each sub-package maintainer update their docs to bring them in line with the guidelines.
eteq commentedon Apr 3, 2012
Definitely a good idea - I have some specific ideas that also tie into package organization that I was planning to post shortly to astropy-dev.
There's also a need to reformat some of the guidelines and re-organize the developer section - this shouldn't take too long, but I'm waiting for #187 to merge because its kind of painful to edit the docs until that's in.
Another item that might take a bit more time (and which I'd be happy to farm out to anyone interested...) would be editing the github instructions to better reflect what our in-practice workflow has become - I've seen a few people express confusion that I think is mostly because those pages are not entirely applicable to the way we've actually ended up doing things.
astrofrog commentedon Apr 20, 2012
Here are some ideas for how we can improve what's already there:
I think we should try and do as much of this as possible before 0.1, because at the moment, I feel that if I told someone to install astropy, they wouldn't actually know what to do with it (apart from use the 'legacy' packages).
astrofrog commentedon Apr 20, 2012
Just cc-ing @taldcroft, @iguananaut, and @mdboom to bring this discussion to their attention.
@eteq - I know you want to have a discussion on the mailing list, but I figured that to get things moving, we could at least have a discussion with the current sub-package maintainers so we can converge on this somewhat before going to the list.
embray commentedon Apr 20, 2012
Thanks @astrofrog for summarizing some of the specifics of what needs to be done--much of this is exactly what I've been thinking and I couldn't have put it better.
You already suggested this in your rough layout, but let me emphasize that all the generated API docs would be better off moved to the end. The "manual" section of the docs should follow more of a continuous narrative. Sure, there isn't necessarily overlap in what all the subpackages do. But it will be better to describe, in some sequence, what you can do with Astropy and how to do it. That goes to your example of having a chapter on "Reading and Writing FITS Files" rather than just "astropy.io.fits Documentation", and assuming the user knows to look there to find out how to do whatever it is they're trying to do.
I've been revising some of the PyFITS documentation as it is, and some of those revisions will probably help improve the narrative in that section of the Astropy docs as well.
And eventually we'll want to add some examples that show multiple parts of Astropy working together. But that's a bit more work.
eteq commentedon Apr 23, 2012
@iguananaut - I'm not sure I fully understand what you're saying here... you think all of the API reference should be at the end, or each sub-package should have an API reference at the end of it? (see my comments below)
@astrofrog - I agree with all your points - in particular I agree with your point that the API/reference should not be a separate independent section. In a project like astropy where the subpackages are fairly separate in what they do, it's a lot more confusing to have the reference separate, and it clearly leads to confusion in the scipy docs where sometimes things that should be in the docstrings end up in the docs, and vice versa.
I also think we need to plan around the API docs always being the most up-to-date, and in some cases the only complete documentation. We should definitely aim for the goal of having good narrative docs, but I think, practically speaking, it will be a long time (if ever) before that goal is achieved, given the constantly-evolving nature of astronomer-produced software. By including the API as part of the documentation, it places a higher premium on ensuring the docstrings are enough to use anything new that gets merged in, and we should always reject anything for which that isn't true.
eteq commentedon Apr 23, 2012
@astrofrog - agreed we should get things moving on this if there are the resources to do so. There are a lot of things I have been "meaning to do," and of course we all know how those schedules slip :) Perhaps the thing to do is to create a sub-package template like that @astrofrog has outlined here and see what people think about that - with that, it will be easier to sub-divide work to various people for different packages. If this sounds good to you, I can go ahead and make a PR with just such a template to send out to the mailing list/discuss here.
A few bullet points of my own for "goals for 0.1":
embray commentedon Apr 23, 2012
@eteq For now I can agree that the different subpackages of astropy are segregated enough in their functionality that it may be fine to leave the docs somewhat segregated as they currently are. But my hope (and maybe this is overly optimistic) is that we (and hopefully other developers from the community) will start looking at these subpackages and finding ways that they can better be integrated with each other and work together (where it makes sense to). At that point it might not make as much sense to treat them as segregated sub-products in the docs or otherwise.
(I don't know if that made much sense--I'm barely on my first cup of coffee.)
eteq commentedon Apr 24, 2012
@iguananaut I see what you're saying, and I agree that there are major advantages to be gained by cross-connecting the subpackages. However, I still think at the API level, it makes sense to subdivide by package - sphinx makes it easy to jump between the subpackages as long as you reference everything correctly, so the location doesn't matter that much from a reference point of view, and I think it does improve readability if you just want to use stuff from the one package.
I definitely agree that once we have some good cases, we want to provide some useful examples of how connecting different subpackages is useful (already we have
astropy.io.voandastropy.io.table, I suppose). Perhaps we should add a root-TOC section called something like "Examples of subpackage interactions" or something, to encourage people to populate it ASAP?kbarbary commentedon Apr 24, 2012
I agree with @iguananaut that once I know what something does, I'm mainly interested in getting to the API in the docs. But, I also see why you might want to keep the reference/API sections inline. A possible compromise: On the main index page for the docs, the list of subpackages can look like
where Reference/API is a link to the Reference/API section of the subpackage docs. This would leave everything organized by subpackage, but make it easy for people who know what they want to get there fast.
Everything else that @astrofrog and @eteq suggest sounds good to me.
taldcroft commentedon Apr 24, 2012
I agree with the overall view of having API docs available within subpackages. I think this matches the most common user workflow, which is getting to the topic of concern (I need to read a FITS file), scanning narrative docs, then if necessary looking at API docs to get the exact details right. Also, I haven't thought through the full details but I suspect this will also make it easier to maintain standalone packages with less fiddling (but this should not be a big driver for astropy design decisions in any case).
The compromise from @kbarbary may work, but I'm a little worried about how it will look when there are 10 or 15 main topics with all these [Reference] links hanging off the end. In any case I would propose generally calling these docs the "Reference" docs and not using the word "API", which is not informative to many astronomers.
Would it be possible to please the power users by generating a page with a Reference TOC that just links into all the subpackage Reference sections? You wouldn't be able to navigate between subpackage reference sections (with next/prev) but this would probably be OK.
astrofrog commentedon Apr 25, 2012
@taldcroft - the idea of a reference TOC sounds reasonable, and should be easy enough to do.
@eteq - a template for docs layout sounds good!
eteq commentedon Apr 27, 2012
I also really like the idea of a separate reference TOC - I'm a little unsure how to do that with sphinx, but I'm sure we can figure it our (although it may require another extension).
eteq commentedon Jun 13, 2012
Much of the stuff likely to get done for v0.1 is in #277, aside from the idea of a reference TOC. I'll make a separate issue for that and close this.
Merge pull request astropy#162 from mwcraig/patch-1
Merge pull request astropy#162 from eteq/add-curr-vers