pypa/pip — pull request #1556 by qwcode (2014-02-11 04:01:16+00:00)
Title: pip docs refactor

@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](https://gist.github.com/qwcode/8431828) 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