Doc layout - #1

I need to look at this in more detail, but a few comments on the minor points:

• I think we should keep the version number at 0.0.0 until we actually start with the coding. Once we have a skeleton for a package, with a setup.py file, then we can switch to setting the version number to astropy.__version__. By the way, I don't like using version numbers with things like 'dev' in them, because it confuses tools that compare version numbers, but that's a discussion for later!
• I agree the 'default' theme is ugly, but the 'sphinxdoc' theme is quite nice (it's built-in). Have you tried it out? I think customizing themes should be a very low priority for now, and we should just pick the least worse default one.

There is an issue in the gitwash guidelines - some instances of ipython haven't been changed to astropy, e.g. on cloning the repository:

git clone git://github.com/ipython/astropy.git

I'm not 100% sure I understand how you pulled in the gitwash stuff, so it's probably easier for you to fix.

My last comment for now is that I hadn't realized how long the gitwash guidelines are. We'll definitely want to make sure that we have a simple one page overview to summarize things - also, the gitwash pages mention multiple possible workflows, but we might want to simplify that (we can probably remove stuff to do with patches being sent to mailing lists!). Finally, the gitwash guidelines mixes a bit how to do things in git, and how to actually contribute to the package, which I see as separate issues to some extent. Anyway, all this to say that I think this is fine for now as a placeholder, but we definitely want to go through and keep only what we really need, and potentially separate the real workflow for AstroPy from the git tutorial.

The ipython bit was just a typo when I got the gitwash documentation... so that's corrected (and a small piece I forgot to do before that adds in a favicon to the page build).

I actually am not a huge fan of the 'sphinxdoc' theme for other projects because it always looks the same and is not customizable at all - it has to look exactly the same font and color-wise as the sphinx docs. default, meanwhile can be totally altered and customized anyway you want (fonts, colors,styles, etc.) - the astropysics docs were made that way, and as you can see they actually end up looking more like the sphinx docs - in principal you can get it to look nearly identical if you choose the same color and font scheme.

And yes, I 100% agree the gitwash needs to get cleaned up for our scheme... it doesn't bother me that "how to use git" mixes with "how to contribute" because that allows actually useful examples (which is what I think most people want). We'll need to have this a bit more separated out if we use the non-git VCS option workflow schemes, though.

Ok, let's just leave the default theme for now, and we can always customize it later as you said. I've been thinking a bit more about the gitwash stuff and I guess I do agree that it make sense to have the git 'tutorial' mesh with 'how to contribute', but I think we'll need to have three main sections in the instructions to reflect what's been discussed so far:

• Recommended (but optional) workflow for affiliated packages - it's up to them to decide if they want to follow that if they are using git, and it's their problem if they mess up the repositories. But at least providing recommended guidelines will help avoid that.
• Required strict workflow for requesting merging into the core package. This can include instructions for making a git fork from an hg repository for example, and also list the option of asking us to do it, etc.
• Required strict workflow for making contributions directly to the core package

We can try and think about this a bit more. I'd be happy to create a fork to try and re-arrange the docs in this way once this pull request is merged (and we can always choose to not use the modified version if it's not adequate)

I should have said, I'm fine with the layout and content otherwise. The suggestion about the gitwash stuff is for future, but this pull request is good to go as far as I'm concerned.