From ef97713d99aa4e69742aa68fd45a63247b5d3ea0 Mon Sep 17 00:00:00 2001
From: David Chase <drchase@google.com>
Date: Fri, 4 Jun 2021 13:08:32 -0400
Subject: [PATCH] gopls/doc: add vetted examples for Sublime Text

Instructions for Sublime Text + LSP + golsp,
including examples for:
  minimal configuration
  adjusting path
  per-project settings

The per-project settings include breadcrumbs helpful
to someone working on Go itself.

Change-Id: I2fe41cd60d7327578bd5bd9999f2459e79e9be4c
Reviewed-on: https://go-review.googlesource.com/c/tools/+/325189
Trust: David Chase <drchase@google.com>
Run-TryBot: David Chase <drchase@google.com>
gopls-CI: kokoro <noreply+kokoro@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Rebecca Stambler <rstambler@golang.org>
---
 gopls/doc/subl.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/gopls/doc/subl.md b/gopls/doc/subl.md
index ad7e667491..bd130ef521 100644
--- a/gopls/doc/subl.md
+++ b/gopls/doc/subl.md
@@ -8,4 +8,70 @@ Use the [LSP] package. After installing it using Package Control, do the followi
 
 Finally, you should familiarise yourself with the LSP package's *Settings* and *Key Bindings*. Find them under the menu item **Preferences > Package Settings > LSP**.
 
+## Examples
+Minimal global LSP settings, that assume **gopls** and **go** appear on the PATH seen by Sublime Text:<br>
+```
+{
+    "clients": {
+        "gopls": {
+             "enabled": true,
+         }
+    }
+}
+```
+
+Global LSP settings that supply a specific PATH for finding **gopls** and **go**, as well as some settings for Sublime LSP itself:
+```
+{
+    "clients": {
+        "gopls": {
+            "enabled": true,
+            "env": {
+                "PATH": "/path/to/your/go/bin",
+            }
+        }
+    },
+    // Recommended by https://agniva.me/gopls/2021/01/02/setting-up-gopls-sublime.html
+    // except log_stderr mentioned there is no longer recognized.
+    "show_references_in_quick_panel": true,
+    "log_debug": true,
+    // These two are recommended by LSP-json as replacement for deprecated only_show_lsp_completions
+    "inhibit_snippet_completions": true,
+    "inhibit_word_completions": true,
+ }
+ ```
+
+LSP and gopls settings can also be adjusted on a per-project basis to override global settings.
+```
+{
+    "folders": [
+        {
+            "path": "/path/to/a/folder/one"
+        },
+        {
+            // If you happen to be working on Go itself, this can be helpful; go-dev/bin should be on PATH.
+            "path": "/path/to/your/go-dev/src/cmd"
+        }
+     ],
+    "settings": {
+        "LSP": {
+            "gopls": {
+                "env": {
+                    "PATH": "/path/to/your/go-dev/bin:/path/to/your/go/bin",
+                    "GOPATH": "",
+                },
+                "settings": {
+                    "experimentalWorkspaceModule": true
+                }
+            }
+        },
+        // This will apply for all languages in this project that have
+        // LSP servers, not just Go, however cannot enable just for Go.
+        "lsp_format_on_save": true,
+    }
+}
+```
+
+Usually changes to these settings are recognized after saving the project file, but it may sometimes be necessary to either restart the server(s) (**Tools > LSP > Restart Servers**) or quit and restart Sublime Text itself.
+
 [LSP]: https://packagecontrol.io/packages/LSP