[WIP] Docs refactor

[Ivoz]

For pypa/packaging.python.org#5

Since virtualenv only consists of two/three commands at its heart (virtualenv, activate and deactivate) I thought a "quickstart" for these, without explaining what the heck they do and how to use them, would be somewhat unhelpful.

WIP -

• look over options and make sure they're ok
• add all necessary env vars (needed?)
• refactor the explained options from the bottom of the userguide to reference? (e.g --extra-search-dir, --relocate)
• Write a proper module documentation for virtualenv (in relation to its extensibility)?
• Other sections could be removed / need major rewrite?

Request for comment, on the above

[qwcode]

oh, you did it. let me build it out and look later tonight....

[qwcode]

the idea is for usage and options to be dynamic. see pip's usage page and it's use of extensions.

[jezdez]

-1 virtualenv isn't a fast moving target when it comes to options, so I don't see a reason to not write the doc manually and add some proper prose to it

[Ivoz]

Is this really needed? Virtualenv isn't nearly as big as pip nor does it change as much. Plus pip needs to start using .. option:: directives itself!

[qwcode]

@jezdez, to be clear, this is for the "Reference Guide" portion, which I was intending to be a mostly "mechanical" rendering of the facts. The "User Guide" can be for more topical prose that covers the 80% cases.

see here for context : https://gist.github.com/qwcode/8431828
the "Pypa Template" idea is part of my plan on making the PUG links to Pypa docs appear more consistent and less jolting. I was planning on shuffling pip as well to this structure.

this may seem bit silly for virtualenv, since it's so small, but for pip and setuptools, I think it's significant.

[qwcode]

In order to see your local docs built using the RTD theme, see pip's conf.py
https://github.com/pypa/pip/blob/develop/docs/conf.py#L103
it helps to see it locally using the RTD theme
you'll need to install sphinx_rtd_theme

[qwcode]

capital "R"