[tools] gopls/doc Update Sublime Text documentation to LSP-gopls
Gerrit Bot (Gerrit)
Gerrit Bot has uploaded this change for review.
gopls/doc Update Sublime Text documentation to LSP-gopls
This Pull Request updates the `gopls` documentation for Sublime Text.
`gopls` should be integrated in Sublime Text by using the official helper plugin [LSP-gopls](https://github.com/sublimelsp/LSP-gopls).
[LSP-gopls](https://github.com/sublimelsp/LSP-gopls) is recommended because:
- it provides a plug and play solution, allowing new users to get up and running quickly
- it automatically installs and updates the `gopls` executable
- it provides settings competition (when LSP-json is active)
I adapted the existing examples to the new plugin.
Change-Id: Ieebb840419ba4629cd73641ace58456686f3d8e1
GitHub-Last-Rev: 66218e636feff6499b916c7d9a72594468fa70fb
GitHub-Pull-Request: golang/tools#377
---
M gopls/doc/subl.md
1 file changed, 82 insertions(+), 64 deletions(-)
diff --git a/gopls/doc/subl.md b/gopls/doc/subl.md
index a2b1585..540015f 100644
--- a/gopls/doc/subl.md
+++ b/gopls/doc/subl.md
@@ -1,81 +1,77 @@
# Sublime Text
-Use the [LSP] package. After installing it using Package Control, do the following:
+Setting up Sublime Text for Golang development.
-* Open the **Command Palette**
-* Find and run the command **LSP: Enable Language Server Globally**
-* Select the **gopls** item. Be careful not to select the similarly named *golsp* by mistake.
+## Installation
-Finally, you should familiarise yourself with the LSP package's *Settings* and *Key Bindings*. Find them under the menu item **Preferences > Package Settings > LSP**.
+Make sure Go is installed and available in your `PATH`. The [Go Documentation][golang-installation] get Go up and running quickly.
+You can verify that Go is properly installed and available by typing `go help` in a terminal. The command should print a help text instead of an error message.
-## Examples
-Minimal global LSP settings, that assume **gopls** and **go** appear on the PATH seen by Sublime Text:<br>
-```
+Use [Package Control] to install the following plugins:
+
+- [LSP] provides language server support in Sublime Text
+- [LSP-gopls] the helper plugin for gopls
+- (optionally) [Gomod] and [Golang Build] for gomod support and a Go build system
+
+gopls is automatically installed and activated when a `.go` file is opened.
+
+## Configuration
+
+Here are some ways to configure the package and the language server. See [the documentation][gopls-settings] for all available settings.
+
+### Global configuration
+- Configure the LSP plugin by navigating to `Preferences > Package Settings > LSP > Settings` or by executing the `Preferences: LSP Settings` command in the command palette.
+- Configure gopls by navigating to `Preferences > Package Settings > LSP > Servers > LSP-gopls` or by executing the `Preferences: LSP-gopls Settings` command in the command palette.
+
+### Project-specific configuration
+From the command palette run `Project: Edit Project` and add your settings in:
+
+```js
{
- "clients": {
- "gopls": {
- "enabled": true,
- }
+ "settings": {
+ "LSP": {
+ "LSP-gopls": {
+ "settings": {
+ // Put your settings here
+ }
+ }
}
+ }
}
```
-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,
- }
- ```
+### Formatting
-LSP and gopls settings can also be adjusted on a per-project basis to override global settings.
-```
+It is recommended to auto-format Go files using the language server when saving.
+This can be enabled either globally in the LSP settings (see above) or for the Go syntax only.
+
+To enable formatting for the Go syntax only, open a Go file and open the syntax-specific settings by navigating to `Preferences > Settings - Syntax Specific`.
+
+Add `"lsp_format_on_save": true` to the outermost curly braces:
+
+```js
+// These settings override both User and Default settings for the Go syntax
{
- "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": {
- // To use a specific version of gopls with Sublime Text LSP (e.g., to try new features in development)
- "command": [
- "/path/to/your/go/bin/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,
- }
+ "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.
+### Custom gopls executable
+You can use a custom gopls executable by setting the path in the LSP-gopls settings (see above).
+```js
+{
+ "command": [
+ "path/to/custom/gopls"
+ ],
+}
+```
+
+
+[Package Control]: https://packagecontrol.io/installation
[LSP]: https://packagecontrol.io/packages/LSP
+[LSP-gopls]: https://packagecontrol.io/packages/LSP-gopls
+[Gomod]: https://packagecontrol.io/packages/Gomod
+[Golang Build]: https://packagecontrol.io/packages/Golang%20Build
+[golang-installation]: https://golang.org/doc/install
+[gopls-settings]: https://github.com/golang/tools/blob/master/gopls/doc/settings.md
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
Gopher Robot (Gerrit)
Congratulations on opening your first change. Thank you for your contribution!
Next steps:
A maintainer will review your change and provide feedback. See
https://go.dev/doc/contribute#review for more info and tips to get your
patch through code review.
Most changes in the Go project go through a few rounds of revision. This can be
surprising to people new to the project. The careful, iterative review process
is our way of helping mentor contributors and ensuring that their contributions
have a lasting impact.
Gerrit Bot (Gerrit)
Attention is currently required from: Robert Findley, Hyang-Ah Hana Kim.
Gerrit Bot uploaded patch set #2 to this change.
gopls/doc Update Sublime Text documentation to LSP-gopls
This Pull Request updates the `gopls` documentation for Sublime Text.
`gopls` should be integrated in Sublime Text by using the official helper package [LSP-gopls](https://github.com/sublimelsp/LSP-gopls).
[LSP-gopls](https://github.com/sublimelsp/LSP-gopls) is recommended because:
- it provides a plug and play solution, allowing new users to get up and running quickly
- it automatically installs and updates the `gopls` executable
- it provides settings competition (when LSP-json is active)
I adapted the existing examples to the new plugin.
Change-Id: Ieebb840419ba4629cd73641ace58456686f3d8e1
GitHub-Last-Rev: 66218e636feff6499b916c7d9a72594468fa70fb
GitHub-Pull-Request: golang/tools#377
---
M gopls/doc/subl.md
1 file changed, 82 insertions(+), 64 deletions(-)
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
Gerrit Bot (Gerrit)
Attention is currently required from: Robert Findley, Hyang-Ah Hana Kim.
Gerrit Bot uploaded patch set #3 to this change.
gopls/doc Update Sublime Text documentation to LSP-gopls
This Pull Request updates the `gopls` documentation for Sublime Text.
`gopls` should be integrated in Sublime Text by using the official helper package [LSP-gopls](https://github.com/sublimelsp/LSP-gopls).
[LSP-gopls](https://github.com/sublimelsp/LSP-gopls) is recommended because:
- it provides a plug and play solution, allowing new users to get up and running quickly
- it automatically installs and updates the `gopls` executable
- it provides settings competition (when LSP-json is active)
I adapted the existing examples to the new plugin.
Change-Id: Ieebb840419ba4629cd73641ace58456686f3d8e1
GitHub-Last-Rev: 0b6e1432303388efed2ff0139213d753ce81135c
GitHub-Pull-Request: golang/tools#377
---
M gopls/doc/subl.md
1 file changed, 82 insertions(+), 64 deletions(-)
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
Hyang-Ah Hana Kim (Gerrit)
Attention is currently required from: Robert Findley, David Chase.
3 comments:
Patchset:
Awesome. Thanks.
File gopls/doc/subl.md:
Patch Set #3, Line 7:
The [Go Documentation][golang-installation] get Go up and running quicklyFollow the Go Documentation to ...?
Patch Set #3, Line 14:
gomod supports/gomod support/go.mod file syntax highlighting/
(wondered what's gomod support :-)
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
Gerrit Bot (Gerrit)
Attention is currently required from: Robert Findley, David Chase, Hyang-Ah Hana Kim.
Gerrit Bot uploaded patch set #4 to this change.
gopls/doc Update Sublime Text documentation to LSP-gopls
This Pull Request updates the `gopls` documentation for Sublime Text.
`gopls` should be integrated in Sublime Text by using the official helper package [LSP-gopls](https://github.com/sublimelsp/LSP-gopls).
[LSP-gopls](https://github.com/sublimelsp/LSP-gopls) is recommended because:
- it provides a plug and play solution, allowing new users to get up and running quickly
- it automatically installs and updates the `gopls` executable
- it provides settings competition (when LSP-json is active)
I adapted the existing examples to the new plugin.
Change-Id: Ieebb840419ba4629cd73641ace58456686f3d8e1
GitHub-Last-Rev: e7230e42c4ca5725c3cebd83bbe67b7936c35c22
GitHub-Pull-Request: golang/tools#377
---
M gopls/doc/subl.md
1 file changed, 82 insertions(+), 64 deletions(-)
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
David Chase (Gerrit)
Attention is currently required from: Robert Findley, Hyang-Ah Hana Kim.
2 comments:
Patchset:
It was very tricky to figure out exactly how to use LSP-gopls with a different go binary/goroot, so I am not sure those instructions should be removed. I realize that this is not usual-case, but when it is the case, if the instructions are missing, figuring out the right answer is hard.
File gopls/doc/subl.md:
Patch Set #3, Line 50:
outermost curly bracesto be clear, is that at the same level as "settings"? I very much prefer examples that can be looked at or copy-pasted, instead of edit-lists.
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
David Chase (Gerrit)
Attention is currently required from: Robert Findley, Hyang-Ah Hana Kim.
1 comment:
File gopls/doc/subl.md:
Patch Set #3, Line 50:
outermost curly braces
to be clear, is that at the same level as "settings"? I very much prefer examples that can be looke […]
Oops, no, I think this needs an example, because this is not applied to the earlier example, this is applied to JSON not shown here, that I will see with some menu operations.
I think JSON examples are sort of an obligation on doc writers, if an application uses human-editable JSON to manipulate preferences, because there's so much room for confusion and error and all the choices are buried in documentation or somewhere on the internet, instead of being presented in a menu. It's the thing I like least about Sublime Text. (Emacs-lisp is worse, of course).
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
Gerrit Bot (Gerrit)
Attention is currently required from: Robert Findley, Hyang-Ah Hana Kim.
Gerrit Bot uploaded patch set #5 to this change.
gopls/doc Update Sublime Text documentation to LSP-gopls
This Pull Request updates the `gopls` documentation for Sublime Text.
`gopls` should be integrated in Sublime Text by using the official helper package [LSP-gopls](https://github.com/sublimelsp/LSP-gopls).
[LSP-gopls](https://github.com/sublimelsp/LSP-gopls) is recommended because:
- it provides a plug and play solution, allowing new users to get up and running quickly
- it automatically installs and updates the `gopls` executable
- it provides settings competition (when LSP-json is active)
I adapted the existing examples to the new plugin.
Change-Id: Ieebb840419ba4629cd73641ace58456686f3d8e1
GitHub-Last-Rev: 3103b09417cb49592ef5723bb6c0a8c35980f5d4
GitHub-Pull-Request: golang/tools#377
---
M gopls/doc/subl.md
1 file changed, 95 insertions(+), 64 deletions(-)
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
Lucas Alber (Gerrit)
Attention is currently required from: Robert Findley, David Chase, Hyang-Ah Hana Kim.
2 comments:
Patchset:
It was very tricky to figure out exactly how to use LSP-gopls with a different go binary/goroot, so […]
Instructions for a custom gopls binary were already present in patchset 3. I added instructions for custom environment variables.
File gopls/doc/subl.md:
Patch Set #3, Line 50:
outermost curly bracesto be clear, is that at the same level as "settings"? I very much prefer examples that can be looke […]
There is an example in the next code-block. `lsp_format_on_save` can be applied to the global sublime settings, syntax specific settings as well as to the LSP plugin settings. This example shows syntax specific settings (recommended) in which `lsp_format_on_save` must be added to the same level as for example "color_scheme" or "font_face".
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
Lucas Alber (Gerrit)
Attention is currently required from: Robert Findley, David Chase, Hyang-Ah Hana Kim.
2 comments:
File gopls/doc/subl.md:
Patch Set #3, Line 7:
The [Go Documentation][golang-installation] get Go up and running quicklyFollow the Go Documentation to ... […]
Done
Patch Set #3, Line 14:
gomod support
s/gomod support/go.mod file syntax highlighting/ […]
Done
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.
Robert Findley (Gerrit)
Attention is currently required from: David Chase, Hyang-Ah Hana Kim.
1 comment:
Patchset:
@DrChase gentle ping, WDYT about merging this as-is?
To view, visit change 397715. To unsubscribe, or for help writing mail filters, visit settings.