docs: Add docs for DAP support (#1113)

* docs: Add docs for DAP support Signed-off-by: Charlie Egan <[email protected]> * docs: Lint fixes Signed-off-by: Charlie Egan <[email protected]> --------- Signed-off-by: Charlie Egan <[email protected]>
StyraInc · Sep 17, 2024 · f1606de · f1606de
1 parent 06734bb
commit f1606de
Show file tree

Hide file tree

Showing 7 changed files with 80 additions and 0 deletions.
diff --git a/docs/assets/dap/animation.gif b/docs/assets/dap/animation.gif
diff --git a/docs/assets/dap/breakpoint.png b/docs/assets/dap/breakpoint.png
diff --git a/docs/assets/dap/codeaction.png b/docs/assets/dap/codeaction.png
diff --git a/docs/assets/dap/print.png b/docs/assets/dap/print.png
diff --git a/docs/assets/dap/variables.png b/docs/assets/dap/variables.png
diff --git a/docs/debug-adapter.md b/docs/debug-adapter.md
@@ -0,0 +1,63 @@
+# Debug Adapter
+
+In addition to being a language server, Regal can act as a
+[Debug Adapter](https://microsoft.github.io/debug-adapter-protocol/).
+A Debug Adapter is a program that can communicate with a debugger client,
+such as Visual Studio Code's debugger, to provide debugging capabilities
+for a language.
+
+<img
+  src={require('./assets/dap/animation.gif').default}
+  alt="Animation showing the a debugging session in VS Code"/>
+_A debugging session in VS Code_
+
+:::info
+In order to use the Debug Adapter, you must be using
+[Regal v0.27.0](https://github.com/StyraInc/regal/releases/v0.27.0) or greater,
+as well as a compatible client. See [Editor Support](/regal/editor-support) for
+more details.
+:::
+
+## Getting Started
+
+See the documentation in the Editor Support page for supported clients:
+
+* [Visual Studio Code](/regal/editor-support#visual-studio-code)
+* [Neovim](/regal/editor-support#neovim)
+
+## Features
+
+The Regal Debug Adapter currently supports the following features:
+
+### Breakpoints
+
+Breakpoints allow you to continue execution of a policy until a given point.
+This can be helpful for:
+
+* Inspection of variables at a given point in time
+* Seeing how many times a given block of Rego code is executed, if at all
+* Avoiding the need to step through code as it's run line by line
+
+<img
+  src={require('./assets/dap/breakpoint.png').default}
+  alt="Screenshot of a breakpoint in VS Code"/>
+
+### Variable Inspection
+
+Either at a breakpoint or while stepping through code, you can inspect the
+local variables in scope as well as the contents of the global `input` and
+`data` documents.
+
+`input` will be loaded from `input.json` in the workspace if it exists.
+
+<img
+  src={require('./assets/dap/variables.png').default}
+  alt="Variables being inspected during execution in VS Code"/>
+
+### Print Statements
+
+Print statements are also supported, these are shown in the debug console:
+
+<img
+  src={require('./assets/dap/print.png').default}
+  alt="Print statements shown in the debug output console"/>
diff --git a/docs/editor-support.md b/docs/editor-support.md
@@ -10,6 +10,23 @@ and open a workspace with Rego files.
 
 The plugin will automatically find and use [Regal config](https://docs.styra.com/regal#configuration).
 
+### Debug Adapter Protocol (DAP)
+
+From
+[`v0.17.0`](https://github.com/open-policy-agent/vscode-opa/blob/main/CHANGELOG.md#0170)
+onwards, the OPA extension for Visual Studio Code supports the
+[Regal Debug Adapter](/regal/debug-adapter).
+
+To start a new debug session use the code action `Debug` found above a Rego rule
+or package.
+
+<img
+  src={require('./assets/dap/codeaction.png').default}
+  alt="Code Action in VS Code"/>
+
+Breakpoints can be added by clicking in the gutter to the left of the editor.
+Print statements will be shown in the debug console.
+
 ## Zed
 
 [Zed](https://zed.dev) is a modern open-source code editor with focus on performance and simplicity.