Update documentation

README.md

@@ -11,10 +11,14 @@ own project:
 
 ## Continuous Integration
 
-Scripts are provided for various CI instances in `scripts/continuous_integration`. The intended purpose of each is described below:
-
-* `github_actions`:  exemplifies how to put a project depending on a Drake installation on GitHub Actions
-* `jenkins` : provides complete coverage of additional external example projects
+Scripts are provided for Jenkins or GitHub Actions, depending on the example,
+in each example's respective subdirectory under `.github/`.
+See the `Jenkinsfile` and the top-level `.github/workflows/ci.yml`
+for a complete overview of each respective pipeline.
+The intended purpose of each is described below:
+
+* GitHub Actions: exemplifies how to put a project depending on a Drake installation on GitHub Actions
+* Jenkins: provides complete coverage of additional external example projects
 
 | **Subproject** | **GitHub Actions** | **Jenkins** |
 |:---:|:---:|:---:|

drake_bazel_download/README.md

@@ -8,29 +8,33 @@ For an introduction to Bazel, refer to
 
 ## Instructions
 
-First, install the required Ubuntu packages:
+First, run the `install_prereqs` script to download the Drake source to `/opt/drake/`.
+This also runs Drake's setup script to install the required Ubuntu packages:
 
-```
+```bash
 sudo setup/install_prereqs
 ```
 
-If you don't already have bazel or bazelisk installed, then install bazelisk:
-```
+Additionally, if you don't already have bazel or bazelisk installed, then install bazelisk:
+
+```bash
 sudo setup/install_bazelisk
 ```
 
 Then, to build and test all apps:
-```
+
+```bash
 bazel test //...
 ```
 
 As an example to run a binary directly:
-```
+
+```bash
 bazel run //apps:simple_logging_example
 ```
 
 You may also run the binary directly per the `bazel-bin/...` path that the
 above command prints out; however, be aware that your working directories may
-cause differences.  This is important when using tools like
+cause differences. This is important when using tools like
 `drake::FindResource` / `pydrake.common.FindResource`.
 You may generally want to stick to using `bazel run` when able.

drake_bazel_external/README.md

@@ -7,20 +7,23 @@ For an introduction to Bazel, refer to
 
 ## Instructions
 
-First, run the `install_prereqs` script to download the drake source and run
-drake's source setup script to install the required Ubuntu packages:
+First, run the `install_prereqs` script to download the Drake source to `drake-master/`
+(from the current directory). This also runs Drake's setup script to
+install the required Ubuntu packages:
 
-```
-setup/install_prereqs.sh
+```bash
+sudo setup/install_prereqs
 ```
 
 Then, to build and test all apps:
-```
+
+```bash
 bazel test //...
 ```
 
 As an example to run a binary directly:
-```
+
+```bash
 bazel run //apps:simple_logging_example
 ```
 
@@ -35,7 +38,8 @@ You may generally want to stick to using `bazel run` when able.
 To use Drake sources on disk instead of downloaded from github, pass the flag
 ``--override_module=drake=/home/user/stuff/drake`` to bazel on the command line
 or add a line such as the following to ``user.bazelrc`` in the current directory:
-```
+
+```bash
 build --override_module=drake=/home/user/stuff/drake
 ```
 

drake_bazel_external_legacy/README.md

@@ -12,20 +12,23 @@ For an introduction to Bazel, refer to
 
 ## Instructions
 
-First, run the `install_prereqs` script to download the drake source and run
-drake's source setup script to install the required Ubuntu packages:
+First, run the `install_prereqs` script to download the Drake source to `drake-master/`
+(from the current directory). This also runs Drake's setup script to
+install the required Ubuntu packages:
 
-```
-setup/install_prereqs.sh
+```bash
+sudo setup/install_prereqs
 ```
 
 Then, to build and test all apps:
-```
+
+```bash
 bazel test //...
 ```
 
 As an example to run a binary directly:
-```
+
+```bash
 bazel run //apps:simple_logging_example
 ```
 

drake_cmake_external/CMakeLists.txt

@@ -96,7 +96,7 @@ set(DRAKE_PREFIX "${PROJECT_BINARY_DIR}/drake-prefix")
 ExternalProject_Add(drake
   DEPENDS eigen fmt spdlog
   URL https://github.com/RobotLocomotion/drake/archive/master.tar.gz
-  # Or from a commit (download and use "shashum -a 256 'xxx.tar.gz'" on it to
+  # Or from a commit (download and use "shasum -a 256 'xxx.tar.gz'" on it to
   # get the URL_HASH.
   # URL https://github.com/RobotLocomotion/drake/archive/65c4366ea2b63278a286b1e22b8d464d50fbe365.tar.gz
   # URL_HASH SHA256=899d98485522a7cd5251e50a7a6b8a64e40aff2a3af4951a3f0857fd938cafca

drake_cmake_external/README.md

@@ -4,11 +4,12 @@ This pulls in Drake using the CMake `ExternalProject_Add(drake)` mechanism.
 
 ## Instructions
 
-First, run the `install_prereqs` script to download the drake source and run
-drake's source setup script to install the required Ubuntu packages:
+First, run the `install_prereqs` script to download the Drake source to `drake-master/`
+(from the current directory). This also runs Drake's setup script to
+install the required Ubuntu packages:
 
-```
-setup/install_prereqs.sh
+```bash
+sudo setup/install_prereqs
 ```
 
 Keep in mind that within the top-level CMakeLists, the drake source is once
@@ -19,7 +20,7 @@ changed within that version, then the script ran above must also be modified.
 Once all necessary dependencies have been installed, build and run tests
 using CMake:
 
-```
+```bash
 mkdir build
 cd build
 cmake ..

drake_cmake_installed/README.md

@@ -6,56 +6,54 @@ This uses the CMake `find_package(drake)` mechanism to find an installed instanc
 
 These instructions are only supported for Ubuntu 22.04 (Jammy).
 
-```shell
+```bash
 ###############################################################
 # Install Prerequisites
 ###############################################################
-# Various system dependencies
-sudo setup/install_prereqs
 
-# (Optionally) Install GTest
-# You could also explicitly pull gtest into the CMake build directly:
-#     https://github.com/google/googletest/tree/master/googletest
-sudo apt-get install libgtest-dev
-ls
-mkdir ~/gtest && cd ~/gtest && cmake /usr/src/gtest && make
-sudo cp *.a /usr/local/lib
+# Download Drake source to /opt/drake/ and install
+# various system dependencies
+sudo setup/install_prereqs
 
 ###############################################################
 # Install Drake to $HOME/drake
 ###############################################################
 
+# There are a few options to install drake:
+
 # 1) A specific version (date-stamped)
-# curl -O https://drake-packages.csail.mit.edu/drake/nightly/drake-20240214-jammy.tar.gz
+curl -O https://drake-packages.csail.mit.edu/drake/nightly/drake-20240214-jammy.tar.gz
 
 # 2) The latest (usually last night's build)
 curl -O https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-jammy.tar.gz
 tar -xvzf drake-latest-jammy.tar.gz -C $HOME
 
 # 3) Manual Installation
-# git clone https://github.com/RobotLocomotion/drake.git
-# (mkdir drake-build && cd drake-build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake ../drake && make)
+git clone https://github.com/RobotLocomotion/drake.git
+(cd drake && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake .. && make)
 
 # 4) Manual Installation w/ Licensed Gurobi
 # Install & setup gurobi (http://drake.mit.edu/bazel.html?highlight=gurobi#install-on-ubuntu)
-# git clone https://github.com/RobotLocomotion/drake.git
-# (mkdir drake-build && cd drake-build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake -DWITH_GUROBI=ON ../drake && make)
+git clone https://github.com/RobotLocomotion/drake.git
+(cd drake && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake -DWITH_GUROBI=ON .. && make)
 
 ###############################################################
 # Build Everything
 ###############################################################
+
 git clone https://github.com/RobotLocomotion/drake-external-examples.git
-cd drake-external-examples
-mkdir drake_cmake_installed-build && cd drake_cmake_installed-build
-cmake -DCMAKE_PREFIX_PATH=$HOME/drake ../drake_cmake_installed
+cd drake-external-examples/drake_cmake_installed
+mkdir build && cd build
+cmake -DCMAKE_PREFIX_PATH=$HOME/drake ..
 make
+
 # (Optionally) Run Tests
 make test
 ```
 
 # Examples
 
-Drake specific Examples:
+Drake-specific examples:
 
 * [Simple Continuous Time System](src/simple_continuous_time_system/README.md)
 * [Particle System](src/particle)
@@ -70,11 +68,11 @@ These build instructions are adapted from those above, but will use an existing
 source tree of Drake (but *not* installing it to `$HOME/drake`),
 build this project, and then run all available tests:
 
-```shell
+```bash
 # Build development version of Drake, ensuring no old artifacts are present.
 cd drake  # Where you are developing.
-rm -rf ../drake-build && mkdir ../drake-build && cd ../drake-build
-cmake ../drake  # Configure Gurobi, Mosek, etc, if needed.
+rm -rf build && mkdir build && cd build
+cmake .. # Configure Gurobi, Mosek, etc, if needed.
 # Build locally.
 make
 # Record the build's install directory.
@@ -84,11 +82,11 @@ drake_install=${PWD}/install
 cd ..
 # Clone this repository if you have not already.
 git clone https://github.com/RobotLocomotion/drake-external-examples.git
-cd drake-external-examples
+cd drake-external-examples/drake_cmake_installed
 # Follow "Install Prerequisites" in the instructions linked above if you
 # have not already.
-mkdir drake_cmake_installed-build && cd drake_cmake_installed-build
-cmake -DCMAKE_PREFIX_PATH=${drake_install} ../drake_cmake_installed
+mkdir build && cd build
+cmake -DCMAKE_PREFIX_PATH=${drake_install} ..
 make
 ctest
 ```

drake_cmake_installed_apt/README.md

@@ -12,12 +12,14 @@ Install the `drake-dev` APT package by following the instructions found at:
 <https://drake.mit.edu/apt.html>
 
 For this example, also install the `build-essential` and `cmake` APT packages:
+
 ```bash
 sudo apt-get update
-sudo apt-get --no-install-recommends install build-essential cmake 
+sudo apt-get --no-install-recommends install build-essential cmake
 ```
 
 To build the `drake_cmake_installed_apt` example:
+
 ```bash
 mkdir build
 cd build
@@ -26,6 +28,7 @@ make
 ```
 
 To run the `drake_cmake_installed_apt` tests:
+
 ```bash
 cd build
 ctest .