[docs] Provide pointers to known editor plugins and extensions

[kbobyrev]

Summary

Many editors provide extensions and plugins with LSP Client functionality. Many of these are known to work with Clangd, this patch points users to the relevant resources for better experience.

[kbobyrev]

I need to

• Complete last two sections
• Make sure everything is rendered as expected
• Proof-read the text

[ilya-biryukov]

Do we want to keep the docs for different editors separate or do we want to put them all into a single page in case we add more editors?
I would vouch for keeping them on a single page, but that's not a strong opinion. Wonder what other people think?

[kbobyrev]

In D51297#1214297, @ilya-biryukov wrote:

Do we want to keep the docs for different editors separate or do we want to put them all into a single page in case we add more editors?
I would vouch for keeping them on a single page, but that's not a strong opinion. Wonder what other people think?

This one is pretty long and might scare some people off if we push this to the main documentation file IMO. However, creating a separate page for Vim integration might make it harder to discover the page itself, which is another problem. It seems like both options have their downsides, I'm not sure which one is better.

[ioeric]

In D51297#1214297, @ilya-biryukov wrote:

Do we want to keep the docs for different editors separate or do we want to put them all into a single page in case we add more editors?
I would vouch for keeping them on a single page, but that's not a strong opinion. Wonder what other people think?

Looking at the length of the vim integration doc, I think it might make sense to keep the full vim integration doc separate. However, it might still make sense to have short/simplified quick start instructions plus a link to the full doc for more details in the main doc.

clang-tools-extra/docs/index.rst

29 ↗

(On Diff #162660)

clangd-vim is not a top-level project. I think this should be linked from clangd documentation.

clang/docs/ClangFormat.rst

97 ↗

(On Diff #162660)

We could recomend formatting with clangd in clangd doc, but advertising here seems a bit odd. I'd suggest dropping this.

And to be fair, clang-format editor plugins seem to be provide finer controls than LSP clients.

[JonasToth]

Very nice! Switching to clangd means that YCM is not necessary anymore?

[kbobyrev]

clang/docs/ClangFormat.rst

97 ↗

(On Diff #162660)

I agree. clang-format plugins (e.g. vim-clang-format) aren't advertised here, though. But I was going to have another patch on that, this might be useful for clang-format users; for example I discovered that plugin long after I started using clang-format.

[ilya-biryukov]

In D51297#1214313, @kbobyrev wrote:

In D51297#1214297, @ilya-biryukov wrote:

Do we want to keep the docs for different editors separate or do we want to put them all into a single page in case we add more editors?
I would vouch for keeping them on a single page, but that's not a strong opinion. Wonder what other people think?

This one is pretty long and might scare some people off if we push this to the main documentation file IMO. However, creating a separate page for Vim integration might make it harder to discover the page itself, which is another problem. It seems like both options have their downsides, I'm not sure which one is better.

Exactly the trade-off we're facing here. Not sure either. I'm personally not scared of big documents if there are links/TOCs to navigate to relevant parts. The "hard to find" bit looks like more of a problem to me.

[kbobyrev]

In D51297#1214321, @JonasToth wrote:

Very nice! Switching to clangd means that YCM is not necessary anymore?

Hi! Yeah, basically I wanted to follow up on the mailing list after I get some docs in, but you found this earlier :)

The good thing about Clangd (from my perspective) is that as long as the plugin has LSP integration, users are free to use whatever plugin they want (also, YCM decided that LSP support is out of the scope of their project).

I am personally using LanguageClient-neovim almost all the time and I certainly had the best experience out of every other plugin/workflow I tried so far (although, as you can see, the setup is not trivial and there are actually few downsides of the LanguageClient-neovim). The other thing is that I'm using NeoVim and while I have tried this setup for the "plain" Vim I don't have too much user experience from that perspective yet, but most of my team members use Vim and we're currently looking into that.

[JonasToth]

Very nice :)

I will try to get it running for vim 8.0 on ubuntu 18.04 (hopefully this
week!) and share if i had success :)

Am 27.08.2018 um 16:57 schrieb Kirill Bobyrev via Phabricator:

kbobyrev added a comment.

In https://reviews.llvm.org/D51297#1214321, @JonasToth wrote:

Very nice! Switching to clangd means that YCM is not necessary anymore?

Hi! Yeah, basically I wanted to follow up on the mailing list after I get some docs in, but you found this earlier :)

The good thing about Clangd (from my perspective) is that as long as the plugin has LSP integration, users are free to use whatever plugin they want (also, YCM decided https://github.com/Valloric/ycmd/issues/515 that LSP support is out of the scope of their project).

I am personally using LanguageClient-neovim almost all the time and I certainly had the best experience out of every other plugin/workflow I tried so far (although, as you can see, the setup is not trivial and there are actually few downsides of the LanguageClient-neovim). The other thing is that I'm using NeoVim and while I have tried this setup for the "plain" Vim I don't have too much user experience from that perspective yet, but most of my team members use Vim and we're currently looking into that.

https://reviews.llvm.org/D51297

[kbobyrev]

Complete two last paragraphs, address few comments.

We haven't figured out whether we should suggest using this particular workflow at this point, but we're discussing the options.

[kbobyrev]

Now that there's a Wiki page on how to use Clangd with LanguageClient-neovim, we should just redirect (Neo)Vim users to that page.

[kbobyrev]

Ping; this one just redirects to the appropriate Wiki entry on GitHub.

[ilya-biryukov]

I would stamp this from my side, but concerns whether we should recommend YCM's LSP-based completer instead are probably still there.
@sammccall, WDYT?

[kbobyrev]

In D51297#1225546, @ilya-biryukov wrote:

I would stamp this from my side, but concerns whether we should recommend YCM's LSP-based completer instead are probably still there.
@sammccall, WDYT?

Yes, I can see your point, but I think this is better than nothing (which we currently have). Also, having the guide in LanguageClient-neovim Wiki might be easier for the users since they can change something (e.g. when the plugin is updated and the docs become outdated) and have an easier time finding out about the option.

Would love to hear some feedback from @ioeric and @sammccall.

[ioeric]

In D51297#1228441, @kbobyrev wrote:

In D51297#1225546, @ilya-biryukov wrote:

I would stamp this from my side, but concerns whether we should recommend YCM's LSP-based completer instead are probably still there.
@sammccall, WDYT?

Yes, I can see your point, but I think this is better than nothing (which we currently have). Also, having the guide in LanguageClient-neovim Wiki might be easier for the users since they can change something (e.g. when the plugin is updated and the docs become outdated) and have an easier time finding out about the option.

Would love to hear some feedback from @ioeric and @sammccall.

I also support having some instructions/pointers on editor integration. That said, I think we should have a section "Editor integration" with a list of editor clients that are known to work with clangd, instead of having a section just for vim. Something like:

#Editor (or client?) integration

##Vim
Some LSP clients that are known to work with clangd:
 - nvim, LanguageClient-neovim ..
 - ...

## vscode

## emacs?

What do you think?

[kadircet]

In D51297#1228725, @ioeric wrote:

I also support having some instructions/pointers on editor integration. That said, I think we should have a section "Editor integration" with a list of editor clients that are known to work with clangd, instead of having a section just for vim. Something like:

#Editor (or client?) integration

##Vim
Some LSP clients that are known to work with clangd:
 - nvim, LanguageClient-neovim ..
 - ...

## vscode

## emacs?

What do you think?

Sorry I am trespassing, just wanted to say +1 to this.

[kbobyrev]

Outline the structure for "Editor Integration" section which is to be filled with other options later.

[ioeric]

clang-tools-extra/docs/clangd.rst

111

While we are here, would you mind including some other editors/plugins that are known to work with clangd (just so that people don't think vim is the only editor that works)? E.g. Eglot works on emacs, vscode apparently works as well.

We should also mention that any other LSP clients should work with clangd in theory.

[ioeric]

clang-tools-extra/docs/clangd.rst

114

Thanks!

I would be nice if other editors can get their own sections like vim does :) For example:

vscode
(Something like vscode works well with clangd)

Vim
...

Emacs
(Eglot)

[ioeric]

clang-tools-extra/docs/clangd.rst

114

*It* would be nice...

[kbobyrev]

Create different sections for few editors, link web page with the complete list of LSP clients.

[ilya-biryukov]

clang-tools-extra/docs/clangd.rst

135

Maybe mention it is published in "Visual Studio Marketplace" and can be installed directly from VSCode?

[kbobyrev]

clang-tools-extra/docs/clangd.rst

135

Right, I thought it might make sense to mention that it is developed in-tree here, but since it's the "Editor Integration" section it's probably not worth here and I also didn't notice this mention on top of the documentation page.

[ilya-biryukov]

LGTM

[kbobyrev]

Unfortunately, forgot to add the revision link in the commit message of rCTE342129.

clang-tools-extra/docs/clangd.rst

 +-------------------------------------+------------+----------+
 | Hide Method                         | No         |   No     |
 +-------------------------------------+------------+----------+
 | Implement Method                    | No         |   No     |
 +-------------------------------------+------------+----------+
 | Gen. Getters/Setters                | No         |   No     |
 +-------------------------------------+------------+----------+
 
+Editor Integration
+==================
+
+Any full-featured Language Server Protocol Client implementation should work
+with :program:`Clangd`. This `list
+<https://langserver.org/#implementations-client>` contains information about
+extensions and plugins that are known to work for different editors.
+
+Vim Integration
+---------------
+
+LanguageClient-neovim
+~~~~~~~~~~~~~~~~~~~~~
+
+One of the options of using :program:`Clangd` in :program:`vim` (or
+:program:`nvim`) is to utilize `LanguageClient-neovim
+<https://github.com/autozimu/LanguageClient-neovim>`_ plugin. Please see the
+`Clangd Wiki page
+<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`_ for
+instructions.
+
+VSCode Integration
+------------------
+
+:program:`VSCode` provides `vscode-clangd
+<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`
+which is published in Visual Studio Marketplace and can be installed direcetly
+from :program:`VSCode`.
+
+Emacs Integration
+-----------------
+
+:program:`Emacs` provides `lsp-mode <github.com/emacs-lsp/lsp-mode>` and
+`Eglot <https://github.com/joaotavora/eglot>` plugins for LSP integration.
+
 Getting Involved
 ==================
 
 A good place for interested contributors is the `Clangd developer mailing list
 <http://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with the
 broader community on topics not only related to Clangd, use
 `Clang developer mailing list
 <http://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
 If you're also interested in contributing patches to :program:`Clangd`, take a
 look at the `LLVM Developer Policy
 <http://llvm.org/docs/DeveloperPolicy.html>`_ and `Code Reviews
 <http://llvm.org/docs/Phabricator.html>`_ page. Contributions of new features
 to the `Language Server Protocol
 <https://github.com/Microsoft/language-server-protocol>`_ itself would also be
 very useful, so that :program:`Clangd` can eventually implement them in a
 conforming way.