Update docs

ionide · Jul 14, 2021 · edf77a2 · edf77a2
1 parent 84e2a30
commit edf77a2
Show file tree

Hide file tree

Showing 4 changed files with 165 additions and 44 deletions.
diff --git a/README.mkd b/README.mkd
@@ -12,7 +12,9 @@ _Part of the [Ionide](http://ionide.io) plugin suite._
 
 * Uses LSP-mode of [FsAutoComplete](https://github.com/fsharp/FsAutoComplete) as a backend.
 
-* Powered by [autozimu/LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim).
+* Uses one of the following LSP clients:
+  - Neovim's built-in LSP client (requires Neovim 0.5+)
+  - [autozimu/LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim).
 
 ## Development Status
 
@@ -31,19 +33,20 @@ Feel free to [request features and/or file bug reports](https://github.com/ionid
   - Required to run FsAutoComplete.
   - Very useful for command-line development.
 
-* [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
-  - Required to communicate with FsAutoComplete.
-
-* [fzf](https://github.com/junegunn/fzf) (optional)
-  - Optional dependency of LanguageClient-neovim.
-  - Multi-entry selection UI.
+* If you are using Vim or Neovim (below version 0.5):
+  * [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
+    - Required to communicate with FsAutoComplete.
+  * [fzf](https://github.com/junegunn/fzf) (optional)
+    - Optional dependency of LanguageClient-neovim.
+    - Multi-entry selection UI.
 
 ## Features
 
 - Syntax highlighting
 - Auto completions
 - Error highlighting, error list, and quick fixes based on errors
 - Tooltips
+- Codelens
 - Go to Definition
 - Find all references
 - Highlighting usages
@@ -57,18 +60,51 @@ Feel free to [request features and/or file bug reports](https://github.com/ionid
 
 ## Getting Started
 
-### 1. Install [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
+### Install a LSP Client
+
+#### For Neovim 0.5+
+
+No LSP client plugin is required.
+
+If you are using [neovim/nvim-lspconfig](https://github.com/neovim/nvim-lspconfig), do *not* enable `fsautocomplete`.
+Ionide-vim automatically integrates itself into nvim-lspconfig and will register itself as a server.
+
+#### For Vim / Neovim (below 0.5)
 
-Refer to [their INSTALL.md](https://github.com/autozimu/LanguageClient-neovim/blob/next/INSTALL.md).
+Install [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim). Refer to [their INSTALL.md](https://github.com/autozimu/LanguageClient-neovim/blob/next/INSTALL.md).
 
-```
+Here is the example for [vim-plug](https://github.com/junegunn/vim-plug) package manager.
+
+~~~.vim
 Plug 'autozimu/LanguageClient-neovim', {
     \ 'branch': 'next',
     \ 'do': 'bash install.sh',
     \ }
-```
+~~~
+
+If you are running Windows, you will have to set the value of `do` to `'powershell -ExecutionPolicy Unrestricted .\install.ps1'`.
+
+### Install an autocompletion plugin
+
+We recommend using [Shougo/deoplete.nvim](https://github.com/Shougo/deoplete.nvim).
+
+~~~.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
+~~~
+
+If you are using Neovim 0.5+ and *not* using LanguageClient-neovim, you should also install [deoplete-plugins/deoplete-lsp](https://github.com/deoplete-plugins/deoplete-lsp).
+
+~~~.vim
+Plug 'deoplete-plugins/deoplete-lsp'
+~~~
 
-### 2. Install Ionide-vim
+### Install Ionide-vim
 
 #### Installing with your plugin manager
 
@@ -88,10 +124,6 @@ call dein#add('ionide/Ionide-vim', {
     \ })
 ~~~
 
-#### Installing manually
-
-Clone Ionide-vim to some runtimepath and run `make fsautocomplete`.
-
 #### Installing on Windows
 
 Run `install.ps1` instead of `make fsautocomplete`.
@@ -104,6 +136,10 @@ Plug 'ionide/Ionide-vim', {
      \}
 ~~~
 
+#### Installing manually
+
+Clone Ionide-vim to some runtimepath and run `make fsautocomplete`.
+
 ## Usage
 
 Opening either `*.fs`, `*.fsi` or `*.fsx` files should trigger syntax highlighting and other depending runtime files as well.
@@ -114,11 +150,8 @@ Refer to [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neov
 
 To be added as requested for F#-specific features.
 
-#### `:FSharpLoadWorkspaceAuto`
-  - Searches a workspace (`sln` or `fsproj`) and then load it.
-  - Equivalent to `FSharp.workspaceMode = sln` in Ionide-VSCode.
-  - Automatically called when you open F# files. Can be disabled in settings.
-  - The deep level of directory hierarchy to search can also be configured in settings.
+#### `:FSharpShowLoadedProjects`
+  - Shows the projects currently loaded.
 
 #### `:FSharpParseProject <files>+`
   - Loads specified projects (`sln` or `fsproj`).
@@ -171,21 +204,105 @@ for features provided via Language Server Protocol.
 
 To be added as requested for F#-specific features.
 
+See some examples in [our wiki](https://github.com/ionide/Ionide-vim/wiki/Configuration-Examples) if you're not sure what you would want to set.
+
+#### LSP Client Settings
+
+##### Set the LSP client used by Ionide-vim (default: see below)
+
+Set `g:fsharp#backend` to
+* `nvim` if you want to use neovim's built-in LSP client.
+* `languageclient-neovim` if you want to use [autozimu/LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim).
+* `disable` if you only want the syntax highlighting and the FSI integration.
+
+Default: `nvim` if you are using Neovim 0.5+, `languageclient-neovim` otherwise.
+
+~~~.vim
+let g:fsharp#backend = "languageclient-neovim"
+~~~
+
+##### Set the path to FSAC (default: bundled with Ionide-vim)
+
+By default, Ionide-vim automatically downloads FSAC to its plugin directory.
+If you have a different one e.g. installed as a .NET global tool, you can use it in Ionide-vim by:
+
+~~~.vim
+let g:fsharp#fsautocomplete_command =
+    \ [ 'dotnet',
+    \   'fsautocomplete',
+    \   '--background-service-enabled'
+    \ ]
+~~~
+
+Note: You have to use an array here. Setting a string value to this option will result in an error.
+
+##### Set the keybindings for LSP features (default: not set)
+
+Ionide-vim does *not* provide default keybindings for various LSP features, so you will have to set them yourself.
+
+* If you are using neovim's built-in LSP client, see [here](https://github.com/neovim/nvim-lspconfig#keybindings-and-completion).
+* If you are using LanguageClient-neovim, refer to [their docs](https://github.com/autozimu/LanguageClient-neovim/blob/next/doc/LanguageClient.txt).
+
+Examples are available at [our wiki](https://github.com/ionide/Ionide-vim/wiki/Configuration-Examples).
+
+#### Settings specific to neovim's built-in LSP client
+
+##### Enable/disable the default colorscheme for diagnostics (default: enable)
+
+Neovim's LSP client comes with no default colorscheme, so Ionide-vim sets a VSCode-like one for LSP diagnostics by default.
+You can disable this by the following:
+
+~~~.vim
+let g:fsharp#lsp_recommended_colorscheme = 0
+~~~
+
+##### Enable/disable automatic setup (default: enabled)
+
+With [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig), you would manually call the `setup` function for each LSP servers.
+Ionide-vim does this automatically by default, but you can disable it.
+
+~~~.vim
+let g:fsharp#lsp_auto_setup = 0
+
+lua << EOF
+require'ionide'.setup{}
+EOF
+~~~
+
+##### Enable/disable automatic refreshing CodeLens (default: enabled)
+
+By default, Ionide-vim sets the following so that CodeLens gets refreshed automatically.
+
+~~~.vim
+augroup FSharp_AutoRefreshCodeLens
+    autocmd!
+    autocmd CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
+augroup END
+~~~
+
+You can disable this by setting the below option:
+
+~~~.vim
+let g:fsharp#lsp_codelens = 0
+~~~
+
+**Note: this setting does not affect LanguageClient-neovim's CodeLens feature.**
+Please see [their docs](https://github.com/autozimu/LanguageClient-neovim/blob/next/doc/LanguageClient.txt) for how to configure it.
+
 #### FsAutoComplete Settings
 
 * Ionide-vim uses `snake_case` for the setting names.
   - For FSAC settings only, `CamelCase` can also be used (as it gets serialized to a F# record).
   - If both `snake_case` and `CamelCase` are specified, the `snake_case` one will be preferred.
 * You can change the values at runtime and then notify the changes to FSAC by `:FSharpUpdateServerConfig`.
 * Some of the settings may not work in Ionide-vim as it is lacking the corresponding feature of Ionide-VSCode.
-* If not specified, the recommended default values described on the FSAC's documentation will be used.
-  - If you are using a JSON configuration file though `g:LanguageClient_settingsPath`, the recommended default values will override the settings loaded from it.
+* If not specified, the recommended default values described in the FSAC's documentation will be used.
   - You can disable this by `let g:fsharp#use_recommended_server_config = 0`.
 
 See [the documentation of FSAC](https://github.com/fsharp/FsAutoComplete#settings)
 for the complete list of available settings. Frequently used ones are:
 
-##### Enable/disable automatic calling of `:FSharpLoadWorkspaceAuto` on opening F# files (default: enabled)
+##### Enable/disable automatic loading of the workspace on opening F# files (default: enabled)
 
 ~~~.vim
 let g:fsharp#automatic_workspace_init = 1 " 0 to disable.

diff --git a/autoload/fsharp.vim b/autoload/fsharp.vim
@@ -236,12 +236,28 @@ let s:handlers = {
     \ 'fsharp/notifyWorkspace': 'fsharp#handle_notifyWorkspace',
     \ }
 
+function! s:registerAutocmds()
+    if g:fsharp#backend == 'nvim' && g:fsharp#lsp_codelens
+        augroup FSharp_AutoRefreshCodeLens
+            autocmd!
+            autocmd CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
+        augroup END
+    endif
+    if g:fsharp#backend != 'disable'
+        augroup FSharp_OnCursorMove
+            autocmd!
+            autocmd CursorMoved *.fs,*.fsi,*.fsx  call fsharp#OnCursorMove()
+        augroup END
+    endif
+endfunction
+
 function! fsharp#initialize()
     echom '[FSAC] Initialized'
     if g:fsharp#backend == 'languageclient-neovim'
         call LanguageClient_registerHandlers(s:handlers)
     endif
     call fsharp#updateServerConfig()
+    call s:registerAutocmds()
 endfunction
 
 

diff --git a/ftplugin/fsharp.vim b/ftplugin/fsharp.vim
@@ -11,7 +11,7 @@ endif
 
 " set some defaults
 let s:script_root_dir = expand('<sfile>:p:h') . "/../"
-if !exists('g:fsharp#languageserver_command')
+if !exists('g:fsharp#fsautocomplete_command')
     let s:fsac = fnamemodify(s:script_root_dir . "fsac/fsautocomplete.dll", ":p")
 
     " check if FSAC exists
@@ -21,7 +21,7 @@ if !exists('g:fsharp#languageserver_command')
         finish
     endif
 
-    let g:fsharp#languageserver_command =
+    let g:fsharp#fsautocomplete_command =
         \ ['dotnet', s:fsac,
             \ '--background-service-enabled'
         \ ]
@@ -85,7 +85,7 @@ if g:fsharp#backend == 'languageclient-neovim'
     if !has_key(g:LanguageClient_serverCommands, 'fsharp')
         let g:LanguageClient_serverCommands.fsharp = {
             \ 'name': 'fsautocomplete',
-            \ 'command': g:fsharp#languageserver_command,
+            \ 'command': g:fsharp#fsautocomplete_command,
             \ 'initializationOptions': {},
             \}
         if g:fsharp#automatic_workspace_init
@@ -105,12 +105,12 @@ elseif g:fsharp#backend == 'nvim'
     if !exists('g:fsharp#lsp_auto_setup')
         let g:fsharp#lsp_auto_setup = 1
     endif
-    if !exists('g:fsharp#lsp_auto_start')
-        let g:fsharp#lsp_auto_start = 1
-    endif
     if !exists('g:fsharp#lsp_recommended_colorscheme')
         let g:fsharp#lsp_recommended_colorscheme = 1
     endif
+    if !exists('g:fsharp#lsp_codelens')
+        let g:fsharp#lsp_codelens = 1
+    endif
     if g:fsharp#lsp_auto_setup
         lua ionide.setup{}
     endif
@@ -144,18 +144,7 @@ if g:fsharp#backend == 'languageclient-neovim'
         autocmd User LanguageClientStarted call fsharp#initialize()
     augroup END
 endif
-if g:fsharp#backend == 'nvim'
-    augroup FSharp_AutoRefreshCodeLens
-        autocmd!
-        autocmd CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
-    augroup END
-endif
 if g:fsharp#backend != 'disable'
-    augroup FSharp_OnCursorMove
-        autocmd!
-        autocmd CursorMoved *.fs,*.fsi,*.fsx  call fsharp#OnCursorMove()
-    augroup END
-
     com! -buffer FSharpUpdateFSAC call fsharp#updateFSAC()
     com! -buffer FSharpReloadWorkspace call fsharp#reloadProjects()
     com! -buffer FSharpShowLoadedProjects call fsharp#showLoadedProjects()

diff --git a/lua/ionide/init.lua b/lua/ionide/init.lua
@@ -38,13 +38,12 @@ end
 local function get_default_config()
   local result = {}
   local auto_init = vim.g['fsharp#automatic_workspace_init']
-  local auto_start = vim.g['fsharp#lsp_auto_start']
 
   result.name = "ionide"
-  result.cmd = vim.g['fsharp#languageserver_command']
+  result.cmd = vim.g['fsharp#fsautocomplete_command']
   result.root_dir = util.root_pattern("*.sln", "*.fsproj", ".git")
   result.filetypes = {"fsharp"}
-  result.autostart = (auto_start == 1)
+  result.autostart = true
   result.handlers = create_handlers()
   result.init_options = { AutomaticWorkspaceInit = (auto_init == 1) }
   result.on_init = function() fn['fsharp#initialize']() end