kbobyrev updated this revision to Diff 162808.
kbobyrev marked an inline comment as done.
kbobyrev added a comment.

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.


https://reviews.llvm.org/D51297

Files:
  clang-tools-extra/docs/clangd-vim.rst
  clang-tools-extra/docs/clangd.rst

Index: clang-tools-extra/docs/clangd.rst
===================================================================
--- clang-tools-extra/docs/clangd.rst
+++ clang-tools-extra/docs/clangd.rst
@@ -108,6 +108,14 @@
 | Gen. Getters/Setters                | No         |   No     |
 +-------------------------------------+------------+----------+
 
+
+Vim Integration
+===============
+
+For more information on how to setup :program:`Clangd` for :program:`vim`,
+please see `Clangd Vim integration page
+<https://clang.llvm.org/extra/clangd.html>`_.
+
 Getting Involved
 ==================
 
Index: clang-tools-extra/docs/clangd-vim.rst
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/clangd-vim.rst
@@ -0,0 +1,209 @@
+======================
+Clangd Vim integration
+======================
+
+.. contents::
+
+.. toctree::
+   :maxdepth: 1
+
+:program:`Clangd` can be used within (Neo)Vim.
+
+Vim LSP plugins
+===============
+
+There are several existing LSP plugins for (Neo)Vim, most notably:
+
+* `LanguageClient-neovim <https://github.com/autozimu/LanguageClient-neovim>`_
+  is probably the one getting most traction at the moment. It supports more
+  features than its counterparts and also works better for NeoVim users
+  (despite the name it also works for regular Vim).
+* `vim-lsc <https://github.com/natebosch/vim-lsc>`_ provides convenient key
+  bindings and has a lot of options, but lacks few important features such as
+  `code formatting <https://github.com/natebosch/vim-lsc/issues/98>`_ which can
+  be used instead to invoke
+  `Clang-Format <https://clang.llvm.org/docs/ClangFormat.html>`_.
+* `vim-lsp <https://github.com/prabirshrestha/vim-lsp>`_ is another (Neo)Vim
+  async plugin which offers LSP integration, but it also lacks several features
+  like `code actions <https://github.com/prabirshrestha/vim-lsp/issues/155>`_ (
+  needed for applying Fix-Its).
+
+Given that `LanguageClient-neovim` supports more features at the moment, this
+document will focus on setting up this plugin in your (Neo)Vim.
+
+Configuring `LanguageClient-neovim`
+===================================
+
+You can see the generic setup guide in `plugin's README
+<https://github.com/autozimu/LanguageClient-neovim#quick-start>`_.
+Here we will focus on a way to build a complete :program:`Clangd` setup.
+
+The recommended way of installing plugins is `vim-plug
+<https://github.com/junegunn/vim-plug>`_ which offers various ``Plug`` options
+used for easier plugin setup.
+
+.. code-block:: vim
+
+  Plug 'autozimu/LanguageClient-neovim', {
+      \ 'branch': 'next',
+      \ 'do': 'bash install.sh',
+      \ }
+
+Next step is to specify :program:`Clangd` invokation command. The easiest way to
+do that is just telling ``LanguageClient-neovim`` to run :program:`clangd`
+binary (assuming it is already in the ``$PATH``):
+
+.. code-block:: vim
+
+  let g:LanguageClient_serverCommands = {
+      \ 'cpp': ['clangd'],
+      \ }
+
+That's all, this is a complete ``LanguageClient-neovim`` setup! However, it is
+recommended to use few other plugins and setup custom key bindings for better
+user experience. Please refer to the `Recommended Settings` section.
+
+Recommended Settings
+====================
+
+``LanguageClient-neovim`` has multiple options for the completion management:
+
+* `deoplete <https://github.com/Shougo/deoplete.nvim>`_
+* `ncm2 <https://github.com/ncm2/ncm2>`_
+* Vim's ``omnifunc`` (used by default)
+
+For best experience, it is advised to use ``deoplete``. This is one of the most
+advanced completion manager which is very flexible and has numerous nice-to-have
+features such as snippets integration (if you are a
+`UltiSnips <https://github.com/SirVer/ultisnips>`_ user). You can install it via
+
+.. code-block:: vim
+
+  if has('nvim')
+    Plug 'Shougo/deoplete.nvim', { 'do': ':UpdateRemotePlugins' }
+  else
+    Plug 'Shougo/deoplete.nvim'
+    Plug 'roxma/nvim-yarp'
+    Plug 'roxma/vim-hug-neovim-rpc'
+  endif
+
+  let g:deoplete#enable_at_startup = 1
+
+Also, by default ``LanguageClient-neovim`` comes without key bindings. Typing
+``call LanguageClient#textDocument_rename()`` each time user would like to
+rename a symbol is not the best experience. Suggested way of a consistent setup
+with the `<leader> key
+<http://vim.wikia.com/wiki/Mapping_keys_in_Vim_-_Tutorial_(Part_3)#Map_leader>`_:
+
+.. code-block:: vim
+
+  function SetLSPShortcuts()
+    nnoremap <leader>ld :call LanguageClient#textDocument_definition()<CR>
+    nnoremap <leader>lr :call LanguageClient#textDocument_rename()<CR>
+    nnoremap <leader>lf :call LanguageClient#textDocument_formatting()<CR>
+    nnoremap <leader>lt :call LanguageClient#textDocument_typeDefinition()<CR>
+    nnoremap <leader>lx :call LanguageClient#textDocument_references()<CR>
+    nnoremap <leader>la :call LanguageClient_workspace_applyEdit()<CR>
+    nnoremap <leader>lc :call LanguageClient#textDocument_completion()<CR>
+    nnoremap <leader>lm :call LanguageClient#LanguageClient_contextMenu()<CR>
+    nnoremap <leader>lh :call LanguageClient#textDocument_hover()<CR>
+    nnoremap <leader>ls :call LanguageClient_textDocument_documentSymbol()<CR>
+  endfunction()
+
+  augroup LSP
+    autocmd!
+    autocmd FileType cpp,c call SetLSPShortcuts()
+  augroup END
+
+This will ensure that LSP shortcuts are enabled only for source files in C++ or
+C. If you use other language servers for ``LanguageClient-neovim``, just add
+more filetypes to the ``autocmd``.
+
+Another great addition to the setup is `FZF <https://github.com/junegunn/fzf>`_
+integration. It will enable user to use fuzzy matching for something like
+searching through workspace or document symbols. For ``FZF``,
+``LanguageClient-neovim`` will take care of the configuration. All user has to
+do is to install the plugin:
+
+.. code-block:: vim
+
+  Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all' }
+  Plug 'junegunn/fzf.vim'
+
+`echodoc <https://github.com/Shougo/echodoc.vim>`_ can handle the function
+signatures displaying:
+
+.. code-block:: vim
+
+  Plug 'Shougo/echodoc.vim'
+
+  set cmdheight=2
+  let g:echodoc#enable_at_startup = 1
+  let g:echodoc#type = 'signature'
+
+
+``signcolumn`` will appear each time :program:`Clangd` sends a warning or
+provides a diagnostic and the text will be shifted by one column each time
+``signcolumn`` is triggered. To prevent this shift and always show the
+``signcolumn``, use
+
+.. code-block:: vim
+
+  " Always draw the signcolumn.
+  set signcolumn=yes
+
+
+For documentation, see `LanguageClient.txt
+<https://github.com/autozimu/LanguageClient-neovim/blob/next/doc/LanguageClient.txt>`
+or simply call ``:help LanguageClient``.
+
+Troubleshooting
+===============
+
+If you encounter a bug and you are able to reproduce it, :program:`Clangd`
+developers would appreciate a bug submission. To help diagnose the problem, you
+can attach log files and the Mirror File (which stores the LSP input passed to
+:prgram:`Clangd`).
+
+To store ``stderr`` output, you can redirect ``stderr`` to a file and use
+``LanguageClient#debugInfo()`` function:
+
+.. code-block:: vim
+
+  let g:LanguageClient_serverStderr = '/tmp/clangd.stderr'
+
+  function SetLSPShortcuts()
+    " ...
+    " Previous bindings
+    " ...
+    nnoremap <leader>ll :call LanguageClient#debugInfo()<CR>
+  endfunction()
+
+Bonus: Building Global Static Index
+===================================
+
+:program:`Clangd` can provide global completion when given a global static
+index. This index is not rebuilt during the editing process which means that if
+a significant part of the codebase is changed you would have to rebuild it to
+reflect these changes.
+
+To build the global static index, you can use experimental
+:program:`global-symbol-builder` tool. If have copied the
+`compile_commands.json` to the source directory, call:
+
+.. code-block:: console
+
+  global-symbol-builder -executor=all-TUs /path/to/project > llvm-index.yaml
+
+After the index is produced, you can pass it to :program:`Clangd` via
+``-yaml-symbol-file``:
+
+.. code-block:: vim
+
+  let g:LanguageClient_serverCommands = {
+    \ 'cpp': ['clangd', '-yaml-symbol-file=/path/to/llvm-index.yaml',],
+    \ }
+
+The global static index infrastructure is experimental, so please be aware that
+you might encounter some bugs. If you do, please submit a bug report to help
+make the infrastructure better.
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

Reply via email to