From 91ef573a2925c1dc0fc29af45cc4bc4a9ac15a84 Mon Sep 17 00:00:00 2001
From: Jeremy Nimmer <jeremy.nimmer@tri.global>
Date: Mon, 30 Jan 2023 08:37:35 -0800
Subject: [PATCH] [doc] Add VS Code and Emacs integration tips (#18681)

---
 doc/_pages/code_style_tools.md |  9 +++++++++
 doc/_pages/developers.md       |  2 ++
 doc/_pages/emacs.md            | 31 +++++++++++++++++++++++++++++++
 doc/_pages/vscode.md           | 32 ++++++++++++++++++++++++++++++++
 4 files changed, 74 insertions(+)
 create mode 100644 doc/_pages/emacs.md
 create mode 100644 doc/_pages/vscode.md

diff --git a/doc/_pages/code_style_tools.md b/doc/_pages/code_style_tools.md
index 007628931dd1..7348f8cdb371 100644
--- a/doc/_pages/code_style_tools.md
+++ b/doc/_pages/code_style_tools.md
@@ -62,3 +62,12 @@ git clang-format-12 --binary=/usr/bin/clang-format-12 -- [file name]
 # For development on Ubuntu: format a file that has been modified but not staged
 git clang-format-12 --binary=/usr/bin/clang-format-12 -f -- [file name]
 ```
+
+### IDE integration
+
+Most IDEs can run ``clang-format`` automatically.
+We have some tips for specific IDEs:
+
+* [CLion](/clion.html#formatting-files)
+* [Emacs](/emacs.html#c-code-formatting)
+* [VS Code](/vscode.html#c-code-formatting)
diff --git a/doc/_pages/developers.md b/doc/_pages/developers.md
index dab363122cb7..54a0ca38e96b 100644
--- a/doc/_pages/developers.md
+++ b/doc/_pages/developers.md
@@ -234,7 +234,9 @@ can look into the question.
 
 # IDE and Text Editor Notes
 
+* [VS Code setup](/vscode.html)
 * [CLion IDE setup](/clion.html)
+* [Emacs setup](/emacs.html)
 * [Eclipse](https://github.com/tkoolen/drake/wiki/Eclipse-setup-(experimental))
 * [Sublime Text Notes](/sublime_text.html)
 * [Unicode Tips & Tricks](/unicode_tips_tricks.html)
diff --git a/doc/_pages/emacs.md b/doc/_pages/emacs.md
new file mode 100644
index 000000000000..56ba79fd234f
--- /dev/null
+++ b/doc/_pages/emacs.md
@@ -0,0 +1,31 @@
+---
+title: Emacs IDE setup
+---
+
+This guide describes how to edit the Drake codebase using Emacs.
+
+If you have tips that would help out other developers, drop us a line and we
+can add them here!
+
+# Setting up Emacs
+
+There is nothing really special to do.
+On Ubuntu ``sudo apt install emacs``.
+
+## Bazel
+
+We recommend [emacs-bazel-mode](https://github.com/bazelbuild/emacs-bazel-mode).
+If you have MELPA configured, use ``M-x package-install bazel``.
+
+## Git
+
+We recommend ``magit``.
+On Ubuntu ``sudo apt install elpa-magit``.
+
+## C++ code formatting
+
+Use ``(require 'clang-format)`` to enable the ``M-x clang-format-...`` family of
+functions. Also check that the customize variable ``clang-format-executable`` is
+set to Drake's preferred value ``clang-format-12``.
+
+<!--- TODO(jwnimmer-tri) Explain 'google-c-style from the styleguide. -->
diff --git a/doc/_pages/vscode.md b/doc/_pages/vscode.md
new file mode 100644
index 000000000000..363b463c9bf0
--- /dev/null
+++ b/doc/_pages/vscode.md
@@ -0,0 +1,32 @@
+---
+title: VS Code IDE setup
+---
+
+This guide describes how to edit the Drake codebase using VS Code.
+
+If you have tips that would help out other developers, drop us a line and we
+can add them here!
+
+# Setting up VS Code
+
+There is nothing really special to do.
+Be sure you've installed the C/C++ extension pack from Microsoft.
+
+## C++ paths
+
+Because VS Code wants to locate all included headers, but Bazel does
+not provide those headers in a single consistent location, it is
+common to get "red squiggles" for included headers, particularly for
+externals like LCM.  So far this does not seem to be avoidable; the
+`"C_Cpp.errorSquiggles": "enabledIfIncludesResolve"` setting does not
+work to solve this problem.
+
+## C++ code formatting
+
+The [Visual Studio docs](https://code.visualstudio.com/docs/cpp/cpp-ide#_code-formatting)
+on code formatting work well. Take note of "Format Document",
+"Format Selection", "Format on save", and "Format on type".
+
+In the VS Code Options configuration, check that the option for
+``C_Cpp: Clang_format_path`` is set to Drake's preferred value
+``clang-format-12``.