docs: update LSP quickstart #28954

gpanders · 2024-05-23T21:29:33Z

The LSP quickstart can act as our true "entrypoint" for answering the question "How do I use LSP in Neovim?" As such, it can be a little more beginniner-friendly than other sections of our help docs by including explanatory comments and a more fleshed out example (including a FileType autocommand).

This also includes some other minor wording updates and points users toward :checkhealth lsp.

The LSP quickstart can act as our true "entrypoint" for answering the question "How do I use LSP in Neovim?" As such, it can be a little more beginniner-friendly than other sections of our help docs by including explanatory comments and a more fleshed out example (including a `FileType` autocommand). This also includes some other minor wording updates and points users toward `:checkhealth lsp`.

MariaSolOs · 2024-05-24T01:18:04Z

runtime/doc/lsp.txt

@@ -25,24 +25,37 @@ Nvim provides an LSP client, but the servers are provided by third parties.
 Follow these steps to get LSP features:

 1. Install language servers using your package manager or by following the
-   upstream installation instruction. You can find language servers here:
+   upstream installation instructions. You can find language servers here:
   https://microsoft.github.io/language-server-protocol/implementors/servers/


Would it make sense to link to nvim-lspconfig instead?

Not all users will have nvim-lspconfig installed, and in any case the hope here is that we can get more users to use LSP without it.

I was not suggesting replacing this by "use nvim-lspconfig", but to use their list of available servers instead since I think it will better reflect which LSPs currently have neovim support.
I don't have strong feelings about it though so it's fine.

MariaSolOs · 2024-05-24T01:19:30Z

runtime/doc/lsp.txt

@@ -25,24 +25,37 @@ Nvim provides an LSP client, but the servers are provided by third parties.
 Follow these steps to get LSP features:

 1. Install language servers using your package manager or by following the
-   upstream installation instruction. You can find language servers here:
+   upstream installation instructions. You can find language servers here:
   https://microsoft.github.io/language-server-protocol/implementors/servers/

 2. Configure the LSP client per language server. See |vim.lsp.start()| or use


I'm not a fan of this first sentence. If this is meant to be an introductory explanation, we should remain consistent of who's the client and who's the server.

Which sentence in particular? Do you have a suggestion on how to reword it?

Oh my bad, it seems like I didn't highlight the right line.
The sentence I don't like is "Configure the LSP client per language server". It makes the role of the client and server confusing IMO.
Maybe we can change it to "Configure each LSP server to communicate with the editor"?

Reworded slightly in cd20761.

MariaSolOs · 2024-05-24T01:20:33Z

runtime/doc/lsp.txt


-4. Configure keymaps and autocmds to use LSP features. See |lsp-config|.
+4. (Optional) Configure keymaps and autocmds to use LSP features. |lsp-config|


For consistency with line 34:

Suggested change

4. (Optional) Configure keymaps and autocmds to use LSP features. |lsp-config|

4. (Optional) Configure keymaps and autocommands to use LSP features. |lsp-config|

clason · 2024-05-24T12:36:26Z

runtime/doc/lsp.txt

-      name = 'my-server-name',
-      cmd = {'name-of-language-server-executable'},
-      root_dir = vim.fs.root(0, {'setup.py', 'pyproject.toml'}),
+    -- Create an event handler for the FileType autocommand


Nitpick: the "event handler" is the "autocommand" (in Vimspeak) for the FileType "event".

Of course, the question is how the audience is here -- whether we should "push" Vimspeak or generic protocol language.

Trying to avoid Vim specific jargon here, where possible. We can leave lots of breadcrumbs (tags) to other help docs to guide the user to learn more, but at this point I want to assume as little a priori knowledge as possible.

clason · 2024-05-24T12:38:42Z

runtime/doc/lsp.txt

+      -- This handler will fire when the buffer's 'filetype' is "python"
+      pattern = 'python',
+      callback = function(ev)
+        -- The buffer number this event is associated with


I would recommend structuring these comments around the intention rather than a technical description. In this case, I would actually not define this here but use the event structure where it is needed (see below).

The intent here was to (hopefully) avoid confusion between "current buffer" and "buffer associated with the autocommand". Pulling the bufnr declaration out allows us to add a separate comment explaining this distinction. But perhaps this is not an important distinction for new users.

clason · 2024-05-24T12:41:28Z

runtime/doc/lsp.txt

+          -- The "root directory" of the project is the parent directory,
+          -- relative to the buffer's file, containing a "setup.py" or
+          -- "pyproject.toml" file
+          root_dir = vim.fs.root(bufnr, {'setup.py', 'pyproject.toml'}),


Suggested change

-- The "root directory" of the project is the parent directory,

-- relative to the buffer's file, containing a "setup.py" or

-- "pyproject.toml" file

root_dir = vim.fs.root(bufnr, {'setup.py', 'pyproject.toml'}),

-- Set the "root directory" to the parent directory of the

-- file in the current buffer (`ev.buf`) that contains either

-- a "setup.py" or a "pyproject.toml" file

root_dir = vim.fs.root(ev.buf, {'setup.py', 'pyproject.toml'}),

The LSP quickstart can act as our true "entrypoint" for answering the question "How do I use LSP in Neovim?" As such, it can be a little more beginniner-friendly than other sections of our help docs by including explanatory comments and a more fleshed out example (including a `FileType` autocommand). This also includes some other minor wording updates and points users toward `:checkhealth lsp`. (cherry picked from commit 28c0494)

github-actions · 2024-05-24T23:33:33Z

Successfully created backport PR for release-0.10:

docs: update LSP quickstart #28989

docs: update LSP quickstart (#28954) The LSP quickstart can act as our true "entrypoint" for answering the question "How do I use LSP in Neovim?" As such, it can be a little more beginniner-friendly than other sections of our help docs by including explanatory comments and a more fleshed out example (including a `FileType` autocommand). This also includes some other minor wording updates and points users toward `:checkhealth lsp`. (cherry picked from commit 28c0494) Co-authored-by: Gregory Anders <8965202+gpanders@users.noreply.github.com>

The LSP quickstart can act as our true "entrypoint" for answering the question "How do I use LSP in Neovim?" As such, it can be a little more beginniner-friendly than other sections of our help docs by including explanatory comments and a more fleshed out example (including a `FileType` autocommand). This also includes some other minor wording updates and points users toward `:checkhealth lsp`.

gpanders requested review from mfussenegger and justinmk May 23, 2024 21:29

github-actions bot added the documentation label May 23, 2024

github-actions bot requested a review from clason May 23, 2024 21:33

MariaSolOs reviewed May 24, 2024

View reviewed changes

clason reviewed May 24, 2024

View reviewed changes

fixup! nits and gnats

0afd9b7

mfussenegger approved these changes May 24, 2024

View reviewed changes

justinmk approved these changes May 24, 2024

View reviewed changes

clason approved these changes May 24, 2024

View reviewed changes

fixup! more rewording

cd20761

MariaSolOs approved these changes May 24, 2024

View reviewed changes

gpanders merged commit 28c0494 into neovim:master May 24, 2024
29 checks passed

gpanders deleted the lsp-quickstart-update branch May 24, 2024 18:35

gpanders added the ci:backport release-0.10 label May 24, 2024

github-actions bot mentioned this pull request May 24, 2024

docs: update LSP quickstart #28989

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update LSP quickstart #28954

docs: update LSP quickstart #28954

gpanders commented May 23, 2024

MariaSolOs May 24, 2024

gpanders May 24, 2024

MariaSolOs May 24, 2024

MariaSolOs May 24, 2024

gpanders May 24, 2024

MariaSolOs May 24, 2024

gpanders May 24, 2024

MariaSolOs May 24, 2024

clason May 24, 2024

gpanders May 24, 2024 •

edited

clason May 24, 2024

gpanders May 24, 2024

clason May 24, 2024

github-actions bot commented May 24, 2024


		4. Configure keymaps and autocmds to use LSP features. See \|lsp-config\|.
		4. (Optional) Configure keymaps and autocmds to use LSP features. \|lsp-config\|

docs: update LSP quickstart #28954

docs: update LSP quickstart #28954

Conversation

gpanders commented May 23, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gpanders May 24, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented May 24, 2024

gpanders May 24, 2024 •

edited