[WIP] Docs refactor

docs/news.rst → docs/changes.rst

@@ -1,19 +1,17 @@
-Changes & News
---------------
+Release History
+===============
 
-.. warning::
+Future
+------
 
-   Python bugfix releases 2.6.8, 2.7.3, 3.1.5 and 3.2.3 include a change that
-   will cause "import random" to fail with "cannot import name urandom" on any
-   virtualenv created on a Unix host with an earlier release of Python
-   2.6/2.7/3.1/3.2, if the underlying system Python is upgraded. This is due to
-   the fact that a virtualenv uses the system Python's standard library but
-   contains its own copy of the Python interpreter, so an upgrade to the system
-   Python results in a mismatch between the version of the Python interpreter
-   and the version of the standard library. It can be fixed by removing
-   ``$ENV/bin/python`` and re-running virtualenv on the same target directory
-   with the upgraded Python.
+1.6.0
+~~~~~
+
+1.11.5
+~~~~~~
 
+Current
+-------
 
 1.11.4 (2014-02-21)
 ~~~~~~~~~~~~~~~~~~~
@@ -197,7 +195,7 @@ Changes & News
   Branden Rolston.
 
 * Fix a bug in the config option parser that prevented setting negative
-  options with environemnt variables. Thanks Ralf Schmitt.
+  options with environment variables. Thanks Ralf Schmitt.
 
 * Allow setting ``--no-site-packages`` from the config file.
 
@@ -333,7 +331,7 @@ Changes & News
 * Updated embedded pip release to 1.0.2.
 
 * Fixed #141 - Be smarter about finding pkg_resources when using the
-  non-default Python intepreter (by using the ``-p`` option).
+  non-default Python interpreter (by using the ``-p`` option).
 
 * Fixed #112 - Fixed path in docs.
 

docs/conf.py

@@ -83,13 +83,14 @@
 # given in html_static_path.
 #html_style = 'default.css'
 
-if os.environ.get('DOCS_LOCAL'):
-    import sphinx_rtd_theme
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-else:
-    # on RTD
-    html_theme = 'default'
+html_theme = 'default'
+if not on_rtd:
+    try:
+        import sphinx_rtd_theme
+        html_theme = 'sphinx_rtd_theme'
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    except ImportError:
+        pass
 
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/development.rst

@@ -0,0 +1,61 @@
+Development
+===========
+
+Contributing
+------------
+
+Refer to the `pip development`_ documentation - it applies equally to
+virtualenv, except that virtualenv issues should filed on the `virtualenv
+repo`_ at GitHub.
+
+Virtualenv's release schedule is tied to pip's -- each time there's a new pip
+release, there will be a new virtualenv release that bundles the new version of
+pip.
+
+Files in the `virtualenv_embedded/` subdirectory are embedded into
+`virtualenv.py` itself as base64-encoded strings (in order to support
+single-file use of `virtualenv.py` without installing it). If your patch
+changes any file in `virtualenv_embedded/`, run `bin/rebuild-script.py` to
+update the embedded version of that file in `virtualenv.py`; commit that and
+submit it as part of your patch / pull request.
+
+.. _pip development: http://www.pip-installer.org/en/latest/development.html
+.. _virtualenv repo: https://github.com/pypa/virtualenv/
+
+Running the tests
+-----------------
+
+Virtualenv's test suite is small and not yet at all comprehensive, but we aim
+to grow it.
+
+The easy way to run tests (handles test dependencies automatically)::
+
+    $ python setup.py test
+
+If you want to run only a selection of the tests, you'll need to run them
+directly with nose instead. Create a virtualenv, and install required
+packages::
+
+    $ pip install nose mock
+
+Run nosetests::
+
+    $ nosetests
+
+Or select just a single test file to run::
+
+    $ nosetests tests.test_virtualenv
+
+Status and License
+------------------
+
+``virtualenv`` is a successor to `workingenv
+<http://cheeseshop.python.org/pypi/workingenv.py>`_, and an extension
+of `virtual-python
+<http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python>`_.
+
+It was written by Ian Bicking, sponsored by the `Open Planning
+Project <http://openplans.org>`_ and is now maintained by a
+`group of developers <https://github.com/pypa/virtualenv/raw/master/AUTHORS.txt>`_.
+It is licensed under an
+`MIT-style permissive license <https://github.com/pypa/virtualenv/raw/master/LICENSE.txt>`_.

docs/index.rst

@@ -1,19 +1,131 @@
-
-virtualenv
+Virtualenv
 ==========
 
-`Changes & News <news.html>`_ |
 `Mailing list <http://groups.google.com/group/python-virtualenv>`_ |
 `Issues <https://github.com/pypa/virtualenv/issues>`_ |
 `Github <https://github.com/pypa/virtualenv>`_ |
 `PyPI <https://pypi.python.org/pypi/virtualenv/>`_ |
 User IRC: #pypa
 Dev IRC: #pypa-dev
 
-.. comment: split here
+Introduction
+------------
+
+``virtualenv`` is a tool to create isolated Python environments.
+
+The basic problem being addressed is one of dependencies and versions,
+and indirectly permissions. Imagine you have an application that
+needs version 1 of LibFoo, but another application requires version
+2. How can you use both these applications?  If you install
+everything into ``/usr/lib/python2.7/site-packages`` (or whatever your
+platform's standard location is), it's easy to end up in a situation
+where you unintentionally upgrade an application that shouldn't be
+upgraded.
+
+Or more generally, what if you want to install an application *and
+leave it be*?  If an application works, any change in its libraries or
+the versions of those libraries can break the application.
+
+Also, what if you can't install packages into the global
+``site-packages`` directory?  For instance, on a shared host.
+
+In all these cases, ``virtualenv`` can help you. It creates an
+environment that has its own installation directories, that doesn't
+share libraries with other virtualenv environments (and optionally
+doesn't access the globally installed libraries either).
 
+.. comment: split here
 
 .. toctree::
    :maxdepth: 2
 
-   virtualenv
+   installation
+   userguide
+   reference
+   development
+   changes
+
+.. warning::
+
+   Python bugfix releases 2.6.8, 2.7.3, 3.1.5 and 3.2.3 include a change that
+   will cause "import random" to fail with "cannot import name urandom" on any
+   virtualenv created on a Unix host with an earlier release of Python
+   2.6/2.7/3.1/3.2, if the underlying system Python is upgraded. This is due to
+   the fact that a virtualenv uses the system Python's standard library but
+   contains its own copy of the Python interpreter, so an upgrade to the system
+   Python results in a mismatch between the version of the Python interpreter
+   and the version of the standard library. It can be fixed by removing
+   ``$ENV/bin/python`` and re-running virtualenv on the same target directory
+   with the upgraded Python.
+
+Other Documentation and Links
+-----------------------------
+
+* `Blog announcement of virtualenv`__.
+
+  .. __: http://blog.ianbicking.org/2007/10/10/workingenv-is-dead-long-live-virtualenv/
+
+* James Gardner has written a tutorial on using `virtualenv with
+  Pylons
+  <http://wiki.pylonshq.com/display/pylonscookbook/Using+a+Virtualenv+Sandbox>`_.
+
+* Chris Perkins created a `showmedo video including virtualenv
+  <http://showmedo.com/videos/video?name=2910000&fromSeriesID=291>`_.
+
+* Doug Hellmann's `virtualenvwrapper`_ is a useful set of scripts to make
+  your workflow with many virtualenvs even easier. `His initial blog post on it`__.
+  He also wrote `an example of using virtualenv to try IPython`__.
+
+  .. _virtualenvwrapper: https://pypi.python.org/pypi/virtualenvwrapper/
+  .. __: http://www.doughellmann.com/articles/CompletelyDifferent-2008-05-virtualenvwrapper/index.html
+  .. __: http://www.doughellmann.com/articles/CompletelyDifferent-2008-02-ipython-and-virtualenv/index.html
+
+* `Pew`_ is another wrapper for virtualenv that makes use of a different
+  activation technique.
+
+  .. _Pew: https://pypi.python.org/pypi/pew/
+
+* `Using virtualenv with mod_wsgi
+  <http://code.google.com/p/modwsgi/wiki/VirtualEnvironments>`_.
+
+* `virtualenv commands
+  <https://github.com/thisismedium/virtualenv-commands>`_ for some more
+  workflow-related tools around virtualenv.
+
+Compare & Contrast with Alternatives
+------------------------------------
+
+There are several alternatives that create isolated environments:
+
+* ``workingenv`` (which I do not suggest you use anymore) is the
+  predecessor to this library. It used the main Python interpreter,
+  but relied on setting ``$PYTHONPATH`` to activate the environment.
+  This causes problems when running Python scripts that aren't part of
+  the environment (e.g., a globally installed ``hg`` or ``bzr``). It
+  also conflicted a lot with Setuptools.
+
+* `virtual-python
+  <http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python>`_
+  is also a predecessor to this library. It uses only symlinks, so it
+  couldn't work on Windows. It also symlinks over the *entire*
+  standard library and global ``site-packages``. As a result, it
+  won't see new additions to the global ``site-packages``.
+
+  This script only symlinks a small portion of the standard library
+  into the environment, and so on Windows it is feasible to simply
+  copy these files over. Also, it creates a new/empty
+  ``site-packages`` and also adds the global ``site-packages`` to the
+  path, so updates are tracked separately. This script also installs
+  Setuptools automatically, saving a step and avoiding the need for
+  network access.
+
+* `zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ doesn't
+  create an isolated Python environment in the same style, but
+  achieves similar results through a declarative config file that sets
+  up scripts with very particular packages. As a declarative system,
+  it is somewhat easier to repeat and manage, but more difficult to
+  experiment with. ``zc.buildout`` includes the ability to setup
+  non-Python systems (e.g., a database server or an Apache instance).
+
+I *strongly* recommend anyone doing application development or
+deployment use one of these tools.

docs/installation.rst

@@ -0,0 +1,58 @@
+Installation
+============
+
+.. warning::
+
+    We advise installing virtualenv-1.9 or greater. Prior to version 1.9, the
+    pip included in virtualenv did not not download from PyPI over SSL.
+
+.. warning::
+
+    When using pip to install virtualenv, we advise using pip 1.3 or greater.
+    Prior to version 1.3, pip did not download from PyPI over SSL.
+
+.. warning::
+
+    We advise against using easy_install to install virtualenv when using
+    setuptools < 0.9.7, because easy_install didn't download from PyPI over SSL
+    and was broken in some subtle ways.
+
+To install globally with `pip` (if you have pip 1.3 or greater installed globally):
+
+::
+
+ $ [sudo] pip install virtualenv
+
+Or to get the latest unreleased dev version:
+
+::
+
+ $ [sudo] pip install https://github.com/pypa/virtualenv/tarball/develop
+
+
+To install version X.X globally from source:
+
+::
+
+ $ curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-X.X.tar.gz
+ $ tar xvfz virtualenv-X.X.tar.gz
+ $ cd virtualenv-X.X
+ $ [sudo] python setup.py install
+
+
+To *use* locally from source:
+
+::
+
+ $ curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-X.X.tar.gz
+ $ tar xvfz virtualenv-X.X.tar.gz
+ $ cd virtualenv-X.X
+ $ python virtualenv.py myVE
+
+.. note::
+
+    The ``virtualenv.py`` script is *not* supported if run without the
+    necessary pip/setuptools/virtualenv distributions available locally. All
+    of the installation methods above include a ``virtualenv_support``
+    directory alongside ``virtualenv.py`` which contains a complete set of
+    pip and setuptools distributions, and so are fully supported.