RobotLocomotion · jwnimmer-tri · Apr 3, 2017 · Apr 3, 2017 · Apr 3, 2017 · Apr 3, 2017
diff --git a/drake/doc/design.rst b/drake/doc/design.rst
@@ -20,8 +20,8 @@ Software Design Documents
 .. Create a bulleted list of links to software design documents (e.g.,
 .. restructured text, PDFs, Google Docs, URLs, etc.)
 
-- *Coming soon: Dynamics 2.0 Design*
-- *Coming soon: System 2.0 Design*
+- *Coming soon: Dynamics Design*
+- *Coming soon: System Design*
 
 
 Mathematical Derivation Documents

diff --git a/drake/doc/developers.rst b/drake/doc/developers.rst
@@ -70,16 +70,18 @@ The following table shows the configurations and platforms that Drake
 officially supports. Supported configurations are tested in continuous
 integration. All other configurations are provided on a best-effort basis.
 
-The "Unix Makefiles" and "Ninja" CMake generators are supported.
+For CMake builds, the "Unix Makefiles" and "Ninja" CMake generators are
+supported.
 
-The supported version of MATLAB is R2015b.
+For CMake builds, the supported version of MATLAB is R2015b.
 
-In CMake, minimal configuration is defined as the minimal required externals
+For CMake builds,
+minimal configuration is defined as the minimal required externals
 from the superbuild. This is configured by turning off all externals using
 ``ccmake`` or ``cmake-gui`` except for ``WITH_EIGEN``, ``WITH_GOOGLETEST``,
 and  ``WITH_GFLAGS``, which should be set to ``ON``.
 
-An incomplete but rapidly growing subset of Drake and Drake's externals is
+Almost all of Drake and Drake's externals are
 supported on Bazel. "Superbuild Deps" are not meaningful in the context
 of Bazel, since there is no configurable superbuild. MATLAB is not supported on
 Bazel, and there are no plans to add support.

diff --git a/drake/doc/from_binary.rst b/drake/doc/from_binary.rst
@@ -1,15 +1,35 @@
-********************************
-Binary installation (mac, linux)
-********************************
+**********************************
+Binary installation (OS X, Ubuntu)
+**********************************
 
-Note: This is still new and relatively untested.  Please report any issues you have.
+Important Note (October, 2016)
+==============================
+
+Drake is currently undergoing a major renovation, with all of the core
+libraries moving into C++.  The examples will move and the existing APIs will
+change.
+
+We are actively working on a binary release of the new software, but are not
+quite finished.  See https://github.com/RobotLocomotion/drake/issues/1766 for
+details.
+
+In the meantime, we suggest you :ref:`build from source <build_from_source>`
+instead.
+
+
+Using older (2015) releases
+===========================
+
+We cannot offer support for older releases, but we still host the binaries for
+reference.
 
 Download the appropriate binary release for your platform
 https://github.com/RobotLocomotion/drake/releases
 Simply extract the archive file into a folder of your choice (mine is called ``drake-distro``).
 
+
 Running MATLAB examples
-=======================
+-----------------------
 
 To run the MATLAB examples, change directories (in MATLAB) into the ``drake-distro/drake`` folder and at the MATLAB prompt do::
 

diff --git a/drake/doc/from_source.rst b/drake/doc/from_source.rst
@@ -8,10 +8,10 @@ Optional: Setting up the MATLAB Compiler
 ========================================
 
 Make sure that the MATLAB executable is in your path.  (e.g., typing ``matlab``
- at the system command line should start an instance of MATLAB).  For example,
- on Mac you might consider
- ``sudo ln -s /Applications/MATLAB_R2014a.app/bin/matlab /usr/bin/matlab``,
- or you can actually add the MATLAB/bin directory to your system path.
+at the system command line should start an instance of MATLAB).  For example,
+on Mac you might consider
+``sudo ln -s /Applications/MATLAB_R2014a.app/bin/matlab /usr/bin/matlab``,
+or you can actually add the MATLAB/bin directory to your system path.
 
 .. _getting_drake:
 
@@ -55,6 +55,10 @@ setup steps:
     ubuntu_trusty
     ubuntu_xenial
 
+See :ref:`supported configurations <supported-configurations>`
+for the configurations and platforms that Drake officially supports.
+All else being equal, we would recommend developers use Ubuntu Xenial.
+
 .. _build_the_collection:
 
 Build the collection

diff --git a/drake/doc/mac.rst b/drake/doc/mac.rst
@@ -19,7 +19,7 @@ Install the prerequisites::
     brew tap-pin robotlocomotion/director
     brew update
     brew upgrade
-    brew install autoconf automake clang-format cmake doxygen gcc glib \
+    brew install autoconf automake bazel clang-format cmake doxygen gcc glib \
       graphviz gtk+ jpeg libpng libtool libyaml mpfr ninja numpy python \
       qt qwt scipy valgrind vtk5 wget
     pip install -U beautifulsoup4 html5lib lxml PyYAML Sphinx

diff --git a/drake/doc/models.rst b/drake/doc/models.rst
@@ -1,8 +1,8 @@
 .. _models:
 
-***************
-Models in Drake
-***************
+*************************
+Geometric Models in Drake
+*************************
 
 .. contents:: `Table of contents`
    :depth: 3

diff --git a/drake/doc/ubuntu_trusty.rst b/drake/doc/ubuntu_trusty.rst
@@ -60,6 +60,20 @@ As OpenJDK 8 is not available on Trusty, install Oracle JDK 8::
     sudo apt-get update
     sudo apt-get install oracle-java8-installer
 
+Bazel
+-----
+
+Bazel is required.  Install Bazel using the instructions at
+https://bazel.build/versions/master/docs/install-ubuntu.html.
+Be sure to install a version that is consistent with Drake's
+:ref:`Supported Configurations <supported-configurations>`.
+
+Here's a short recipe that summarizes the instructions on that page::
+
+    wget https://github.com/bazelbuild/bazel/releases/download/0.4.3/bazel_0.4.3-linux-x86_64.deb
+    echo "0cd6592ac2c5548d566fa9f874a386737e76029f5aabe1f04f8320173a05280d  bazel_0.4.3-linux-x86_64.deb" > bazel_0.4.3-linux-x86_64.deb.sha256
+    sha256sum --check bazel_0.4.3-linux-x86_64.deb.sha256 && sudo dpkg -i bazel_0.4.3-linux-x86_64.deb
+
 
 Other Prerequisites
 -------------------