[doc] Completely revamp installation instructions

doc/_pages/apt.md

@@ -0,0 +1,64 @@
+---
+title: Installation via APT (Ubuntu)
+---
+
+# APT Packages
+
+Drake publishes pre-compiled binaries as APT packages (``*.deb``) for the
+Ubuntu 18.04 (Bionic) and Ubuntu 20.04 (Focal) operating systems. Refer to
+[Supported Configurations](/installation.html#supported-configurations)
+for additional compatibility details.
+
+To learn about other installation methods, refer to
+[Installation and Quickstart](/installation.html).
+
+Drake binary releases incorporate a pre-compiled version of
+[SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
+[Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
+Thanks to Philip E. Gill and Elizabeth Wong for their kind support.
+
+## Stable Releases
+
+To add the Drake APT repository to your machine and install the `drake-dev` package,
+please do the following in order:
+
+If you are using a [minimal](https://wiki.ubuntu.com/Minimal) cloud or
+container image, you may need to install the following packages:
+
+```bash
+sudo apt-get update
+sudo apt-get install --no-install-recommends \
+  ca-certificates gnupg lsb-release wget
+```
+
+Download a copy of the Drake GPG signing key and add it to an APT trusted keychain:
+
+```bash
+wget -qO- https://drake-apt.csail.mit.edu/drake.asc | gpg --dearmor - \
+  | sudo tee /etc/apt/trusted.gpg.d/drake.gpg >/dev/null
+```
+
+Add the Drake repository to your APT sources list:
+
+```bash
+echo "deb [arch=amd64] https://drake-apt.csail.mit.edu/$(lsb_release -cs) $(lsb_release -cs) main" \
+  | sudo tee /etc/apt/sources.list.d/drake.list >/dev/null
+```
+
+Update your local APT package index and install the `drake-dev` package:
+
+```bash
+sudo apt-get update
+sudo apt-get install --no-install-recommends drake-dev
+```
+
+Most content installs to `/opt/drake`, so setting the following environment
+variables may be useful:
+
+  ```bash
+  export LD_LIBRARY_PATH="/opt/drake/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
+  export PATH="/opt/drake/bin${PATH:+:${PATH}}"
+  export PYTHONPATH="/opt/drake/lib/python$(python3 -c 'import sys; print("{0}.{1}".format(*sys.version_info))')/site-packages${PYTHONPATH:+:${PYTHONPATH}}"
+  ```
+
+Refer to [Quickstart](/installation.html#quickstart) for next steps.

doc/_pages/developers.md

@@ -57,34 +57,9 @@ of artifacts distributed with this website.
 * [Detailed Notes on Drake's Unit Tests](/unit_testing_instructions.html)
 * [Downstream Testing (Drake as a Dependency)](/downstream_testing.html)
 
-
 # Supported Configurations
 
-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.
-
-Drake requires a compiler running in C++17 mode.
-
-| Operating System                 | Bazel | CMake | C/C++ Compiler                 | Java                          | Python |
-|----------------------------------|-------|-------|--------------------------------|-------------------------------|--------|
-| Ubuntu 18.04 LTS (Bionic Beaver) | 4.2   | 3.10  | GCC 7.5 (default) or Clang 9   | OpenJDK 11                    | 3.6    |
-| Ubuntu 20.04 LTS (Focal Fossa)   | 4.2   | 3.16  | GCC 9.3 (default) or Clang 9   | OpenJDK 11                    | 3.8    |
-| macOS Catalina (10.15)           | 4.2   | 3.19  | Apple LLVM 12.0.0 (Xcode 12.4) | AdoptOpenJDK 15 (HotSpot JVM) | 3.9    |
-| macOS Big Sur (11)               | 4.2   | 3.19  | Apple LLVM 12.0.0 (Xcode 12.4) | AdoptOpenJDK 15 (HotSpot JVM) | 3.9    |
-
-CPython is the only Python implementation supported. On Ubuntu, amd64
-(i.e., x86_64) is the only supported architecture. On macOS, x86_64 is the only
-supported architecture and running Drake under Rosetta 2 emulation on arm64 is
-not supported. Plans for any future arm64 support on macOS and/or Ubuntu are
-discussed in [issue #13514](https://github.com/RobotLocomotion/drake/issues/13514).
-
-Drake Ubuntu builds assume support for Intel's AVX2 and FMA instructions,
-introduced with the Haswell architecture in 2013 with substantial performance
-improvements in the Broadwell architecture in 2014. Drake is compiled with
-`-march=broadwell` to exploit these instructions (that also works for Haswell
-machines). Drake can be used on older machines if necessary by building from
-source with that flag removed.
+Refer to [Source Installation](/from_source.html#supported-configurations).
 
 ## Configuration Management Non-Determinism
 
@@ -105,15 +80,6 @@ If you have tried and are unable to configure your system by
 [following the instructions](/from_source.html) please do not hesitate
 to [ask for help](/getting_help.html).
 
-## Binary Packages
-
-The binary releases of Drake are built with GCC 7.5 on Ubuntu 18.04 (Bionic),
-GCC 9.3 on Ubuntu 20.04 (Focal), and Apple LLVM 12.0.0 on macOS Catalina
-(10.15).
-
-The links for these packages are listed in
-[Binary installation](/from_binary.html).
-
 # Issue Tracking
 
 * [GitHub Issue Management](/issues.html)

doc/_pages/docker.md

@@ -1,21 +1,58 @@
 ---
-title: Using the Drake Docker Images From Docker Hub
+title: Installation via Docker
 ---
 
-Drake's continuous integration has nightly jobs that publish the binary
-archives that are described in the [Nightly releases](/from_binary.html#nightly-releases) section. The Ubuntu
-18.04 (Bionic) binary archive is also used to publish a Docker image on
-[Docker Hub](https://hub.docker.com/r/robotlocomotion/drake). You can see the
-available Docker images here:
+# Docker Hub
 
-[https://hub.docker.com/r/robotlocomotion/drake/tags](https://hub.docker.com/r/robotlocomotion/drake/tags)
+Drake publishes pre-compiled binaries as Docker images on
+[Docker Hub](https://hub.docker.com/r/robotlocomotion/drake). Refer to
+[Supported Configurations](/installation.html#supported-configurations)
+for additional compatibility details.
 
-The [latest](https://hub.docker.com/r/robotlocomotion/drake/tags?name=latest)
-image can be pulled from Docker Hub as follows:
+To learn about other installation methods, refer to
+[Installation and Quickstart](/installation.html).
+
+Drake binary releases incorporate a pre-compiled version of
+[SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
+[Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
+Thanks to Philip E. Gill and Elizabeth Wong for their kind support.
+
+## Stable Releases
+
+The latest stable image can be pulled from
+[Docker Hub](https://hub.docker.com/r/robotlocomotion/drake)
+as follows:
+
+```
+docker pull robotlocomotion/drake:X.Y.Z
+```
+
+Refer to [Release Notes](/release_notes/release_notes.html) for a list of
+published X.Y.Z version numbers.
+
+The docker tags for Drake's stable releases are spelled like:
+
+* ``bionic-X.Y.Z`` for the Ubuntu 18.04 image of Drake vX.Y.Z.
+* ``focal-X.Y.Z`` for the Ubuntu 20.04 image of Drake vX.Y.Z.
+* ``X.Y.Z`` is a synonym for one of the above, currently bionic-X.Y.Z.
+
+Refer to [Quickstart](/installation.html#quickstart) for next steps.
+
+## Nightly Releases
+
+The latest nightly image can be pulled from
+[Docker Hub](https://hub.docker.com/r/robotlocomotion/drake)
+as follows:
 
 ```
 docker pull robotlocomotion/drake:latest
 ```
 
-Docker images based on the Ubuntu 20.04 (Focal) binary archive are not
-available.
+The docker tags for Drake's nightly releases are spelled like:
+
+* ``bionic-YYYYMMDD`` for the Ubuntu 18.04 image of Drake as of date YYYY-MM-DD.
+* ``focal-YYYYMMDD`` for the Ubuntu 20.04 image of Drake as of date YYYY-MM-DD.
+* ``YYYYMMDD`` is a synonym for one of the above, currently bionic-YYYYMMDD.
+* ``latest`` is a synonym for the most recent YYYYMMDD.
+
+Refer to [Quickstart](/installation.html#quickstart) for next steps.

doc/_pages/from_binary.md

@@ -1,111 +1,92 @@
 ---
-title: Binary installation (macOS, Ubuntu)
+title: Installation via Direct Download
 ---
 
-# Nightly Releases
+# Binary Packages
 
-Binary packages of Drake for Ubuntu 18.04 (Bionic), Ubuntu 20.04 (Focal) and
-Mac are generated nightly and are tagged ``latest`` or by ``yyyymmdd``. Latest
-releases are available to download at:
-
-* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz)
-* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-focal.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-focal.tar.gz)
-* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz)
-
-Releases for specific days are available as follows:
-`https://drake-packages.csail.mit.edu/drake/nightly/drake-yyyymmdd-bionic|focal|mac.tar.gz`
+Drake publishes pre-compiled binaries as binary downloads (``*.tar.gz``)
+for all supported operating systems.  Refer to
+[Supported Configurations](/installation.html#supported-configurations)
+for compatibility details.
 
-For example: [https://drake-packages.csail.mit.edu/drake/nightly/drake-20191026-bionic.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-20191026-bionic.tar.gz)
-
-
-Note that Drake no longer supports Ubuntu 16.04 (Xenial), but older packages are available here:
-
-* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-xenial.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-xenial.tar.gz)
-* [https://drake-packages.csail.mit.edu/drake/nightly/drake-20191026-xenial.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-20191026-xenial.tar.gz)
-
-Individual packages are archived two years from their date of creation.
-
-Note that for release v0.30.0 and later, Ubuntu binaries require support for
-Intel's AVX2 and FMA instruction sets which were introduced with the Haswell
-architecture in 2013 with substantial performance improvements in the Broadwell
-architecture in 2014. Drake is compiled with `-march=broadwell` to exploit these
-instructions (that also works for Haswell machines). Drake can be used on older
-machines if necessary by building from source with that flag removed.
-
-For the compilers used to produce these releases, see
-[Binary Packages](/developers.html#binary-packages).
+To learn about other installation methods, refer to
+[Installation and Quickstart](/installation.html).
 
 Drake binary releases incorporate a pre-compiled version of
 [SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
 [Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
 Thanks to Philip E. Gill and Elizabeth Wong for their kind support.
 
+## Stable Releases
+
+Binary packages of Drake for Ubuntu 18.04 (Bionic), Ubuntu 20.04 (Focal) and
+Mac are available to download as attachments from Drake's GitHub
+[releases](https://github.com/RobotLocomotion/drake/releases) page:
+
+* [https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-bionic.tar.gz](https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-bionic.tar.gz)
+* [https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-focal.tar.gz](https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-focal.tar.gz)
+* [https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-mac.tar.gz](https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-mac.tar.gz)
 
-## Example Usage
+### Use as a C++ library
 
-An example of how to use the nightly binaries is shown in this
-[example CMake project](https://github.com/RobotLocomotion/drake-external-examples/tree/main/drake_cmake_installed).
+For an example of using a Drake ``*.tar.gz`` image from a CMake project, refer
+to the
+[drake_cmake_installed](https://github.com/RobotLocomotion/drake-external-examples/tree/main/drake_cmake_installed)
+example.
 
-## Binary Installation for Python
+### Use as a Python library
 
-To use Python bindings, see [Binary Installation for Python](/python_bindings.html#installation).
+In most cases, we suggest using our [pip releases](/pip.html), because that
+will be more convenient than manually downloading.  However, if you need both
+C++ and Python API support, then pip will not work.  This section shows
+how to incorporate a manual download into a
+[virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)
+directory.  In the example below, we will name that directory ``env``, but you
+can choose any name.
 
-## Docker Images
+Download the binary release, using one of the links above, or Drake's GitHub
+[releases](https://github.com/RobotLocomotion/drake/releases) page:
 
-You may also use binary releases in Docker images. See
-[Using the Drake Docker Images From Docker Hub](/docker.html)
-for more information.
+```bash
+curl -o drake.tar.gz https://github.com/RobotLocomotion/drake/releases/download/...
+```
 
-## Experimental Packages
+Unpack and install dependencies:
 
-Drake maintainers may build "experimental" packages on demand using Jenkins by
-following [these instructions](/jenkins.html#building-binary-packages-on-demand).
+```bash
+mkdir -p env
+tar -xvzf drake.tar.gz -C env --strip-components=1
+sudo env/share/drake/setup/install_prereqs
+python3 -m virtualenv -p python3 env --system-site-packages
+```
 
-## Historical Note
+To check if this worked, follow the instructions as
+[shown below](#using-the-python-bindings), but either:
 
-Older releases were built around substantial MATLAB support, and are
-described on [release notes page](/release_notes/older_releases.html).
+Activate the virtual environment:
 
-# APT Packages for Monthly Tagged Releases
+```bash
+source env/bin/activate
+````
 
-APT packages are currently available for the Ubuntu 18.04 (Bionic) and
-Ubuntu 20.04 (Focal) operating systems on x86 64-bit architectures.
+Refer to [Quickstart](/installation.html#quickstart) for next steps.
 
-## To Install the Packages
+## Nightly Releases
 
-To add the Drake APT repository to your machine and install the `drake-dev` package,
-please do the following in order:
+Binary packages of Drake for Ubuntu 18.04 (Bionic), Ubuntu 20.04 (Focal) and
+Mac are generated nightly and are available to download at:
 
-1. If you are using a [minimal](https://wiki.ubuntu.com/Minimal) cloud or
-   container image, you may need to install the following packages:
-   ```bash
-   sudo apt-get update
-   sudo apt-get install --no-install-recommends \
-     ca-certificates gnupg lsb-release wget
-   ```
+* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz)
+* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-focal.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-focal.tar.gz)
+* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz)
 
-2. Download a copy of the Drake GPG signing key and add it to an APT trusted keychain:
-   ```bash
-   wget -qO- https://drake-apt.csail.mit.edu/drake.asc | gpg --dearmor - \
-     | sudo tee /etc/apt/trusted.gpg.d/drake.gpg >/dev/null
-   ```
+Older packages for specific dates are available by replacing ``latest`` with an
+8-digit date, e.g., ``20200102`` for January 2nd, 2020.
 
-3. Add the Drake repository to your APT sources list:
-   ```bash
-   echo "deb [arch=amd64] https://drake-apt.csail.mit.edu/$(lsb_release -cs) $(lsb_release -cs) main" \
-     | sudo tee /etc/apt/sources.list.d/drake.list >/dev/null
-   ```
+* [https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-bionic.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-bionic.tar.gz)
+* [https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-focal.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-focal.tar.gz)
+* [https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-mac.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-mac.tar.gz)
 
-4. Update your local APT package index and install the `drake-dev` package:
-   ```bash
-   sudo apt-get update
-   sudo apt-get install --no-install-recommends drake-dev
-   ```
+Individual packages are archived two years from their date of creation.
 
-Most content installs to `/opt/drake`, so setting the following environment
-variables may be useful:
-  ```bash
-  export LD_LIBRARY_PATH="/opt/drake/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
-  export PATH="/opt/drake/bin${PATH:+:${PATH}}"
-  export PYTHONPATH="/opt/drake/lib/python$(python3 -c 'import sys; print("{0}.{1}".format(*sys.version_info))')/site-packages${PYTHONPATH:+:${PYTHONPATH}}"
-  ```
+The installation instructions are identical to stable releases as shown above.