pip docs refactor

[qwcode]

@dstufft, @pfmoore, since this is a big change, I at least want a +0 or +1 from you two.

here it is in built form: http://www.pip-installer.org/en/docs_refactor/index.html

The main thing here is to have a "User Guide" and "Reference Guide" vs the "Usage", "Cookbook", and "Internal Details" sections. The User/Reference distinction is pretty common, and it does the job I think, along with the "Quickstart" we already have.

• "Usage" --> "Reference Guide"
• "Internal Details" --> "Reference Guide" (mostly to the pip install section)
• "Cookbook" --> "User Guide" (with a new "Managing Packages" section that needs some work)

This is also consistent with the Standard Pypa Docs Template that I want all PyPA project docs to follow to appear consistent with each other, which will make the PUG more effective I think,

some details:

• Old pages have been left as stubs with links to where the new content is.
• Each pip command has it's own reference page now, vs all commands being on one page
• "Release Notes" is a first-level section
• The release notes no longer uses sections (but rather emphasis) to avoid TOC noise (a better idea?)
• The "Requirements Files" section is updated with "4 common uses"
• The section on "ImportError: No module named setuptools” (from pip1.4) is now an orphan page that's connected only with a footnote
• I turned off -W in the docs build, because we have warnings now due to pages not being in the TOC.
• mentioned the dev irc channel (#pypa)
• options in the Reference Guide now use .. option:: for better rendering

cc @ncoghlan

[pfmoore]

A couple of minor typos:

1. In User Guide/Configuration/Environment Variables, Dashes (-) have to replaced with is missing a "be"
2. In User Guide/Non-Recursive Upgrades, the layout of the bullet list of requirements could do with more space after the initial requirement (this could be an issue with the overall style, I guess)

Otherwise, I'm still reviewing but looks good so far.

[pfmoore]

+1 from me, this looks good. Thanks for all your work on docs, @qwcode :-)

[dstufft]

Can we leave -W on, and use :orphan: on the pages that aren't in the TOC?

[dstufft]

This could be a seperate PR, but we're dropping support for 3.1 with 1.6 yea?

[qwcode]

oh, didn't know about :orphan:. will do.
yes, drop the 3.1. I'm wanting to merge this to master as well, so, will do that separate.

[dstufft]

Sounds good. +1 from me then.