Drake: Update docs to show how to use Python bindings from a Bazel install

[hongkai-dai]

I tried to set the PYTHONPATH variable to the folder in drake, as suggested in http://drake.mit.edu/python_bindings.html. I can then do import pydrake using python3, but not python2.

Here is the screenshot

[hongkai-dai]

cc @weiqiao

[EricCousineau-TRI]

Sorry about that @weiqiao! The instructions we have are not exactly explicit on how to use the Python bindings.

I'd expect that pydrake would not work just adding bazel-bin/... to PYTHONPATH. (TBH, it's surprising that the Python3 imports work. Will check into that.)
At present, the main (but undocumented) way to do this is to first build and install Drake, and then use this setup to leverage Python bindings.

I have not yet tested this on my machine, but this should be roughly what you need at this point:

cd drake
# Install to a local directory. "~+" means current working directory.
mkdir -p build/install  # Or whatever you want to call it
bazel run //:install -- ~+/build/install
# Update environment variables; solibs and Python.
export LD_LIBRARY_PATH=~+/build/install/lib:${LD_LIBRARY_PATH}
export PYTHONPATH=~+/build/install/lib/python2.7/site-packages:${PYTHONPATH}
# Now try to import pydrake. (Presently supported in Python2. Python3 may work.)
python2 -c 'import pydrake; print(pydrake.__file__)'

If you need a slightly quicker but much hackier way, let me know, but please try this first.

The main functionality of MathematicalProgram, RigidBodyTree, and symbolics is already exposed. The System framework is not yet exposed, but will be soon.

[hongkai-dai]

Thanks @EricCousineau-TRI , it would be great if we could add this setup instruction to http://drake.mit.edu/python_bindings.html

[fbudin69500]

What @EricCousineau-TRI wrote is correct but can be simplified a little bit. It should not be necessary to add:

export LD_LIBRARY_PATH=~+/build/install/lib:${LD_LIBRARY_PATH}

If it doesn't work without this line, there is a bug that I should correct...

[jamiesnape]

See also https://github.com/RobotLocomotion/drake/issues/7507#issuecomment-347643528.

[jamiesnape]

I would encourage people to use cmake instead of bazel run //:install where possible, so that we keep the various details of the install abstracted. We have options for GUROBI, MOSEK, and SNOPT support.

[EricCousineau-TRI]

Gotcha - will cater those instructions towards pointing to CMAKE_INSTALL_PREFIX.
That being said, I would still like to expose Bazel instructions, at least for Drake developers, if they are not consuming it via CMake.

[jamiesnape]

There are a lot of caveats to using that approach, so maybe you can document it internally only (you can consume that package in whatever unsupported way you prefer, but it should be built via CMake setting the correct parameters and calling Bazel).

[EricCousineau-TRI]

Closing, per discussion in #7891.