feat: tweak docs, simplify auto toggle setup

Author: igorlfs

README.md

@@ -2,7 +2,7 @@
 
 > minimalistic [nvim-dap-ui](https://github.com/rcarriga/nvim-dap-ui) alternative
 
-<https://github.com/user-attachments/assets/f75bf535-1d9e-4070-8c7b-96026c343b47>
+<https://github.com/user-attachments/assets/e7d428f2-8361-4407-a4d0-5f3c4f97332e>
 
 ## Installation
 
@@ -27,13 +27,18 @@ return {
 - Watch expressions
 - Manipulate breakpoints
 - Navigate in the call stack
-- Convenient wrapper around `nvim-dap` widgets (scopes) + REPL
+- Inspect all variables in scope[^1]
+- REPL
 
 All of that in a unified, unintrusive window.
 
-## Documentation
+## Getting Started
 
-Visit the full documentation on the [website](https://igorlfs.github.io/nvim-dap-view/home).
+Start a regular debugging session. When desired, you can use `:DapViewOpen` to start the plugin. You can switch to another section using the letter outlined in the `'winbar'` (e.g., `B` for "Breakpoints"). Explore what you can do each section by using `g?` to inspect the keymaps.
+
+Once you're done debugging, you can close the plugin with `:DapViewClose` and then terminate your session as usual.
+
+There's a lot more you can do: `nvim-dap-view` is highly customizable. To learn all the options, commands, tips and tricks, visit the full documentation on the [website](https://igorlfs.github.io/nvim-dap-view/home).
 
 ## Contributing
 
@@ -43,3 +48,5 @@ You can contribute in many ways:
 - If something isn't working, create a [bug report](https://github.com/igorlfs/nvim-dap-view/issues/new?template=bug_report.yml).
 - If you have an idea, file a [feature request](https://github.com/igorlfs/nvim-dap-view/issues/new?template=feature_request.yml). You can also go ahead and implement it yourself with a [PR](https://github.com/igorlfs/nvim-dap-view/compare).
 - If you have some spare bucks, consider [sponsoring](https://github.com/sponsors/igorlfs).
+
+[^1]: using nvim-dap's widgets

docs/src/posts/acknowlegdgements.md

@@ -2,8 +2,8 @@
 title: Acknowledgements
 ---
 
-- [nvim-dap-ui](https://github.com/rcarriga/nvim-dap-ui)  is obviously a huge inspiration!
+- [nvim-dap-ui](https://github.com/rcarriga/nvim-dap-ui) is obviously a huge inspiration!
 - Code to inject treesitter highlights into line is taken from [quicker.nvim](https://github.com/stevearc/quicker.nvim)
-- [lucaSartore](https://github.com/lucaSartore/nvim-dap-exception-breakpoints) for the inspiration for handling exceptions breakpoint
+- [lucaSartore](https://github.com/lucaSartore/nvim-dap-exception-breakpoints) for the inspiration for the handling of exception breakpoints
 - [Kulala](https://github.com/mistweaverco/kulala.nvim) for the creative usage of neovim's `'winbar'` to handle multiple "views"
 - [blink.cmp](https://github.com/Saghen/blink.cmp/blob/main/lua/blink/cmp/config/utils.lua) for the config validation (which is partially taken from a PR to [indent-blankline](https://github.com/lukas-reineke/indent-blankline.nvim/pull/934/files#diff-09ebcaa8c75cd1e92d25640e377ab261cfecaf8351c9689173fd36c2d0c23d94R16))

docs/src/posts/automatic-toggle.md

@@ -7,7 +7,7 @@ Getting started with `nvim-dap` is easier than it sounds! This guide aims to exp
 
 First things first: what is the DAP? Much like the LSP, the DAP is a protocol created to solve a scalability problem: it used to be the case that each text editor had to have a custom integration for each debugger they wanted to support. That means handling the communication was a nightmare: each debugger has its own way of defining breakpoints, or evaluating expressions and whatnot. What DAP brings to the table is a standardization for this communication, massively simplifying the implementation.
 
-To accomplish its goal, the DAP introduces the concept of **debug adapters**: programs that make debuggers comply with the protocol (in fact, many debuggers actually support the protocol natively, such as `gdb`). The first step (after installing the plugin) to setup `nvim-dap` is choosing an adapter, which will depend on the language you're using. You can install an adapter with your system's package manager (or, most likely, using [mason.nvim](https://github.com/mason-org/mason.nvim)). To give some concrete examples, this guides picks `codelldb`: [a powerful adapter](https://github.com/vadimcn/codelldb) which can be used for C, C++ and Rust. Under the hood, `codelldb` (the adapter) uses `lldb` (the debugger). To configure `codelldb` (or any adapter, for that matter) refer to `nvim-dap`'s [wiki](https://codeberg.org/mfussenegger/nvim-dap/wiki/Debug-Adapter-installation). There, we can find a [snippet](https://codeberg.org/mfussenegger/nvim-dap/wiki/C-C---Rust-(via--codelldb)#1-11-0-and-later) to define `codelldb`:
+To accomplish its goal, the DAP introduces the concept of **debug adapters**: programs that make debuggers comply with the protocol (in fact, many debuggers actually support the protocol natively, such as `gdb`). The first step (after installing the plugin) to setup `nvim-dap` is choosing an adapter, which will depend on the language you're using. You can install an adapter with your system's package manager (or using [mason.nvim](https://github.com/mason-org/mason.nvim)). To give some concrete examples, this guides picks `codelldb`: [a powerful adapter](https://github.com/vadimcn/codelldb) which can be used for C, C++ and Rust (and other low level languages). Under the hood, `codelldb` (the adapter) uses `lldb` (the debugger). To configure `codelldb` (or any adapter, for that matter) refer to `nvim-dap`'s [wiki](https://codeberg.org/mfussenegger/nvim-dap/wiki/Debug-Adapter-installation). There, we can find a [snippet](https://codeberg.org/mfussenegger/nvim-dap/wiki/C-C---Rust-(via--codelldb)#1-11-0-and-later) to define `codelldb`:
 
 ```lua
 require("dap").adapters.codelldb = {

docs/src/posts/basics.md

@@ -8,6 +8,7 @@ These are the default options from `nvim-dap-view`. You can use them as referenc
 
 ```lua
 return {
+    auto_toggle = false,
     winbar = {
         show = true,
         -- You can add a "console" section to merge the terminal with the other views

docs/src/posts/configuration.md

@@ -4,7 +4,7 @@ title: Control Bar
 
 The control bar is disabled by default. It can be enabled by setting `winbar.controls.enable`.
 
-<img src="https://i.ibb.co/Hf6V22Hw/dapview-control-bar.png" alt="control bar">
+<img src="https://i.ibb.co/wNbqBnyN/image.png" alt="control bar">
 
 ## Options
 

docs/src/posts/control-bar.md

@@ -4,7 +4,7 @@ title: FAQ
 
 ## Why add `nvim-dap-view` as a dependency for `nvim-dap`?
 
-By default, when launching a new session, `nvim-dap`'s terminal window takes half the screen. As a saner default, `nvim-dap-view` hijacks the terminal window (even if not invoked), making the split take only 12 lines (a setting which is of course, configurable). See [this](https://github.com/rcarriga/nvim-dap-ui/issues/407) related issue (from `nvim-dap-ui`). Of course, this workaround only works if `nvim-dap-view` is loaded when a session starts.
+By default, when launching a new session, `nvim-dap`'s terminal window takes half the screen. As a saner default, `nvim-dap-view` hijacks the terminal window (even if not invoked), making the split take only 12 lines (a setting which is of course, configurable). See [this](https://github.com/rcarriga/nvim-dap-ui/issues/407) related issue (from `nvim-dap-ui`). Of course, for this workaround to work, `nvim-dap-view` has to load before a session starts.
 
 ```lua
 -- Your nvim-dap config
@@ -20,6 +20,10 @@ return {
 }
 ```
 
+## How can I see value of an expression under cursor (hover)?
+
+You can use `nvim-dap` built-in hover widget by calling `require("dap.ui.widgets").hover()`. See `:h dap-widgets` for details.
+
 ## `DapViewWatch` isn't adding the whole variable
 
 In normal mode, `:DapViewWatch` expands the `<cexpr>` under the cursor (see `:h <cexpr>`). By default, this setting works really well for C-like languages, but it can be cumbersome for other languages. To handle that, you can tweak the value for the `'iskeyword'` option (see `:h 'iskeyword'`). For instance, with PHP, you can use `set iskeyword+=$`.
@@ -36,7 +40,7 @@ return {
 
 You can use a commas to define fallback behavior (e.g., `"useopen,newtab"` creates a new tab if the buffer is not found).
 
-## `nvim-dap` is overriding one of the `nvim-dap-view`'s windows on stop
+## `nvim-dap` is overriding one of the `nvim-dap-view`'s windows when the program stops
 
 When `windows.terminal.position` is `right` the views window may be used to display the current frame, because `nvim-dap` has its own internal `switchbuf` setting (see `:h 'switchbuf'`), which defaults to the global `switchbuf` option.  A common solution is to set `nvim-dap`'s `switchbuf` to another value. For instance:
 

docs/src/posts/faq.md

@@ -18,7 +18,7 @@ return {
 
 ## Anchoring
 
-In some scenarios, it's useful to use another window as if it was `nvim-dap-view`'s terminal. One such scenario is when using the `delve` adapter for Go (more specifically, coupled with an `attach` request): the window with the terminal that launched `dlv` can act as if it was the `nvim-dap-view`'s terminal window. By doing that, `nvim-dap-view`'s main window will "follow" `delve`'s window (i.e., `nvim-dap-view`'s main window will open by the side of `delve`'s window). Watch this [video](https://github.com/user-attachments/assets/5dce4b3d-fc01-4be6-9a72-b0f969e34b14) for context.
+In some scenarios, it's useful to use another window as if it was `nvim-dap-view`'s terminal. One such scenario is when using the `delve` adapter for Go (more specifically, when using an `attach` request): the window with the terminal that launched `dlv` can act as if it was the `nvim-dap-view`'s terminal window. By doing that, `nvim-dap-view`'s main window will "follow" `delve`'s window. Watch this [video](https://github.com/user-attachments/assets/5dce4b3d-fc01-4be6-9a72-b0f969e34b14) to see what it looks like.
 
 To achieve that, in addition to hidding the terminal for `delve` (see above), you have to create your own `anchor` function that returns a window number (or `nil`). If `nil` is returned, there's a fallback to the default behavior. Here's a simple function you can use:
 

docs/src/posts/hide-terminal.md

@@ -5,8 +5,7 @@ title: NVIM DAP View
 > Modern, minimalistic debugging UI for neovim
 
 <video controls width="100%">
-    <!-- TODO: update video -->
-    <source src="https://github.com/user-attachments/assets/01c461f7-b77b-4232-bed5-4630f3e7c039" type="video/webm" />
+    <source src="videos/dv-demo.mp4" type="video/mp4" />
     <track kind="captions">
 </video>
 
@@ -89,11 +88,11 @@ The console's default height is resized to match your `nvim-dap-view` configurat
 
 `nvim-dap-view` also provides a "non view" component: the control bar, which exposes some clickable buttons to control your session. It's disabled by default. See details on how to enable and configure it [here](control-bar).
 
-<img src="https://i.ibb.co/Hf6V22Hw/dapview-control-bar.png" alt="control bar">
+<img src="https://i.ibb.co/wNbqBnyN/image.png" alt="control bar">
 
 ## Usage
 
-Learn about `nvim-dap-view`'s [commands](commands) and [keymaps](keymaps) to get started. If it's your first time setting up `nvim-dap`, start [here](basics). By default, `nvim-dap-view` **is not launched automatically** (i.e., when initializing a new session), you have to use the commands or the API. To configure this behavior, visit the [automatic toggle](automatic-toggle) guide.
+Learn about `nvim-dap-view`'s [commands](commands) and [keymaps](keymaps) to get started. If it's your first time setting up `nvim-dap`, start [here](basics). By default, `nvim-dap-view` **is not launched automatically** (i.e., when initializing a new session), you have to use the commands or the API. To change this behavior, enable the `auto_toggle` option.
 
 ## Customization
 

docs/src/posts/home.md

@@ -8,3 +8,7 @@ title: Known Issues
 - Isn't updated when there's no active session
 
 These are limitations with the current API from `nvim-dap`. A new API is [planned](https://github.com/mfussenegger/nvim-dap/issues/1388).
+
+## The terminal buffer is cleared right after a session finishes
+
+Due to a limitation in the way multisession support is currently implemented, it's necessary to eagerly close buffers. Read [this](https://github.com/mfussenegger/nvim-dap/discussions/1523) discussion for details.