Merge pull request RobotLocomotion#10512 from EricCousineau-TRI/featu…

…re/py_doc_pip_example

doc python: Add tip on installing to `virtualenv` environment

doc/python_bindings.rst

@@ -13,6 +13,9 @@ installed as a single package called ``pydrake``.
 
 .. _python-bindings-binary:
 
+Installation
+============
+
 Binary Installation for Python
 ------------------------------
 
@@ -46,6 +49,43 @@ macOS, pay special attention to :ref:`this note <using-python-mac-os-path>`.
 Python 2.7 is currently the only supported version for the bindings supplied
 by the binary packages. To use Python 3.x, see below for building from source.
 
+Inside ``virtualenv``
+^^^^^^^^^^^^^^^^^^^^^
+
+At present, Drake is not installable via ``pip``. However, you can still
+incorporate its install tree into a ``virtualenv``
+`FHS <https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard>`_-like
+environment.
+
+An example for ``python2``, where you should replace ``<venv_path>`` and
+``<platform>``:
+
+.. code-block:: shell
+
+    # Setup drake, and run prerequisites.
+    curl -o drake.tar.gz https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-<platform>.tar.gz
+    mkdir -p <venv_path>
+    tar -xvzf drake.tar.gz -C <venv_path> --strip-components=1
+    # - You may need `sudo` here.
+    <venv_path>/share/drake/setup/install_prereqs
+
+    # Setup a virtualenv over the drake install.
+    python2 -m virtualenv -p python2 <venv_path> --system-site-packages
+
+.. note::
+
+    You can extract Drake into an existing ``virtualenv`` tree if you have
+    already run ``install_prereqs``; however, you should ensure that you have
+    run ``install_prereqs``. Before you do this, you should capture / freeze
+    your current requirements to reproduce your environment if there are
+    conflicts.
+
+To check if this worked, follow the instructions as
+:ref:`shown below <using-python-bindings>`, but either:
+
+*   Use ``<venv_path>/bin/python`` instead of ``python``, or
+*   Source ``<venv_path>/bin/activate`` in your current shell session.
+
 Building the Python Bindings
 ----------------------------
 
@@ -87,10 +127,13 @@ As an example, continuing from the code snippets from above:
 .. _using-python-bindings:
 
 Using the Python Bindings
--------------------------
+=========================
+
+Check Installation
+------------------
 
-To use the Drake Python bindings, follow the steps above to install or build
-Drake. To check this:
+After following the above install steps, check to ensure you can import
+``pydrake``:
 
 .. code-block:: shell
 
@@ -193,7 +236,7 @@ explicitly refer to each symbol:
     simulator = pydrake.systems.analysis.Simulator(diagram)
 
 Differences with C++ API
-========================
+------------------------
 
 In general, the `Python API <pydrake/index.html#://>`_ should be close to the
 `C++ API <doxygen_cxx/index.html#://>`_. There are some exceptions:

setup/mac/binary_distribution/requirements.txt

@@ -6,3 +6,4 @@ pyzmq
 six
 tornado
 u-msgpack-python
+virtualenv

setup/ubuntu/binary_distribution/packages-bionic.txt

@@ -39,6 +39,7 @@ python-six
 python-tk
 python-tornado
 python-u-msgpack
+python-virtualenv
 python-yaml
 python-zmq
 python3
@@ -50,6 +51,7 @@ python3-six
 python3-tk
 python3-tornado
 python3-u-msgpack
+python3-virtualenv
 python3-yaml
 python3-zmq
 qtbase5-dev

setup/ubuntu/binary_distribution/packages-xenial.txt

@@ -38,6 +38,7 @@ python-scipy
 python-six
 python-tk
 python-tornado
+python-virtualenv
 python-yaml
 python-zmq
 qtbase5-dev