initial
This commit is contained in:
fwastring
commit
baa0056244
352 changed files with 47928 additions and 0 deletions
166
docs/guide/getting_started.md
Normal file
166
docs/guide/getting_started.md
Normal file
|
|
@ -0,0 +1,166 @@
|
|||
# Getting Started
|
||||
The PowerShell Editor Services project provides a Language Server Protocol (LSP)
|
||||
HTTP server that runs outside the editor. The server supplies rich editor
|
||||
functionality like code completion, syntax highlighting, and code annotation.
|
||||
This document will guide you through getting a minimal setup working with
|
||||
several editors.
|
||||
|
||||
## Editors
|
||||
1. [Neovim](#neovim)
|
||||
|
||||
## Neovim
|
||||
|
||||
### Install the Server
|
||||
Download and extract the PowerShell Editor Services server from the
|
||||
[releases page](https://github.com/PowerShell/PowerShellEditorServices/releases)
|
||||
into a directory of your choice. Remember the path that you extract the
|
||||
project into.
|
||||
```powershell
|
||||
$DownloadUrl = 'https://github.com/PowerShell/PowerShellEditorServices/releases/latest/download/PowerShellEditorServices.zip';
|
||||
$ZipPath = "$HOME/Desktop/PowerShellEditorServices.zip";
|
||||
$InstallPath = "$HOME/Desktop/PowerShellEditorServices";
|
||||
Invoke-WebRequest -Method 'GET' -Uri $DownloadUrl -OutFile $ZipPath;
|
||||
Expand-Archive -Path $ZipPath -DestinationPath $InstallPath;
|
||||
```
|
||||
|
||||
### Install Neovim's Quickstart LSP Configurations
|
||||
Neovim has a repository of quickstart LSP configurations for a number of
|
||||
languages, including PowerShell. Install the quickstart LSP configuration into
|
||||
one of the package directories inside `$XDG_CONFIG_HOME`. The path
|
||||
`$XDG_CONFIG_HOME` will vary depending on which operating system you are on:
|
||||
|
||||
| OS | Path |
|
||||
| ---------- | -------------------------- |
|
||||
| Windows | `$HOME/AppData/local/nvim` |
|
||||
| *nix/macOS | `$HOME/.config/nvim` |
|
||||
|
||||
The easiest way is to install the quickstart configuration is to clone the
|
||||
repository using git:
|
||||
```powershell
|
||||
git clone https://github.com/neovim/nvim-lspconfig.git "$HOME/AppData/local/nvim/pack/complete/start/nvim-lspconfig"
|
||||
```
|
||||
|
||||
Alternatively, you can extract the zip file into the same place:
|
||||
```powershell
|
||||
$DownloadUrl = 'https://github.com/neovim/nvim-lspconfig/archive/refs/heads/master.zip';
|
||||
$ZipPath = "$HOME/AppData/local/nvim/nvim-lspconfig.zip";
|
||||
$InstallPath = "$HOME/AppData/local/nvim/pack/complete/start/nvim-lspconfig";
|
||||
Invoke-WebRequest -Method 'GET' Uri $DownloadUrl -OutFile $ZipPath;
|
||||
Expand-Archive -Path $ZipPath -DestinationPath $InstallPath;
|
||||
```
|
||||
|
||||
> NOTE: If the corresponding neovim configuration and package directories have
|
||||
> not been created yet, create them before installing the quickstart LSP
|
||||
> configuration repository.
|
||||
|
||||
### Configure the Server
|
||||
|
||||
#### Setup Keybindings and Path Information
|
||||
Once the basic language configurations have been installed, add this to your
|
||||
`init.lua` located in `$XDG_CONFIG_HOME`:
|
||||
```lua
|
||||
local on_attach = function(client, bufnr)
|
||||
-- Enable completion triggered by <c-x><c-o>
|
||||
vim.api.nvim_set_option_value("omnifunc", "v:lua.vim.lsp.omnifunc", { buf = bufnr })
|
||||
|
||||
local bufopts = { noremap = true, silent = true, buffer = bufnr }
|
||||
vim.keymap.set('n', '<C-k>', vim.lsp.buf.signature_help, bufopts)
|
||||
vim.keymap.set('n', 'gD', vim.lsp.buf.declaration, bufopts)
|
||||
vim.keymap.set('n', 'gd', vim.lsp.buf.definition, bufopts)
|
||||
vim.keymap.set('n', 'gi', vim.lsp.buf.implementation, bufopts)
|
||||
vim.keymap.set('n', 'gr', vim.lsp.buf.references, bufopts)
|
||||
vim.keymap.set('n', 'K', vim.lsp.buf.hover, bufopts)
|
||||
vim.keymap.set('n', '<Leader>ca', vim.lsp.buf.code_action, bufopts)
|
||||
vim.keymap.set('n', '<Leader>f', function() vim.lsp.buf.format { async = true } end, bufopts)
|
||||
vim.keymap.set('n', '<Leader>rn', vim.lsp.buf.rename, bufopts)
|
||||
vim.keymap.set('n', '<Leader>td', vim.lsp.buf.type_definition, bufopts)
|
||||
end
|
||||
|
||||
local home_directory = os.getenv('HOME')
|
||||
if home_directory == nil then
|
||||
home_directory = os.getenv('USERPROFILE')
|
||||
end
|
||||
|
||||
-- The bundle_path is where PowerShell Editor Services was installed
|
||||
local bundle_path = home_directory .. '/Desktop/PowerShellEditorServices'
|
||||
|
||||
require('lspconfig')['powershell_es'].setup {
|
||||
bundle_path = bundle_path,
|
||||
on_attach = on_attach
|
||||
}
|
||||
```
|
||||
|
||||
> NOTE: Be sure to set the bundle_path variable to the correct location,
|
||||
> otherwise the server will not know the path to start the server.
|
||||
|
||||
If you use an `init.vim` file, you may put the keybinding and path configuration
|
||||
in your `init.vim` with the `lua` heredoc syntax instead.
|
||||
```vim
|
||||
lua << EOF
|
||||
-- lua keybindings and path configuration here
|
||||
EOF
|
||||
```
|
||||
|
||||
#### Theme Troubleshooting
|
||||
If you find that your colorscheme appears correctly for a second and then
|
||||
changes to not having full highlighting, you'll need to disable semantic
|
||||
highlighting.
|
||||
Add this line to the `on_attach` function.
|
||||
```lua
|
||||
client.server_capabilities.semanticTokensProvider = nil
|
||||
```
|
||||
|
||||
#### Configure Additional Settings
|
||||
To further configure the server, you can supply settings to the setup table.
|
||||
For example, you can set the code formatting preset to one true brace style
|
||||
(OTBS).
|
||||
```lua
|
||||
require('lspconfig')['powershell_es'].setup {
|
||||
bundle_path = bundle_path,
|
||||
on_attach = on_attach,
|
||||
settings = { powershell = { codeFormatting = { Preset = 'OTBS' } } }
|
||||
}
|
||||
```
|
||||
For a more complete list of options have a look at this schema:
|
||||
[nvim-lsp-installer powershell_es reference](https://github.com/williamboman/nvim-lsp-installer/blob/main/lua/nvim-lsp-installer/_generated/schemas/powershell_es.lua)
|
||||
|
||||
You can also set the bundled PSScriptAnalyzer's custom rule path like so:
|
||||
```lua
|
||||
local custom_settings_path = home_directory .. '/PSScriptAnalyzerSettings.psd1'
|
||||
require('lspconfig')['powershell_es'].setup {
|
||||
bundle_path = bundle_path,
|
||||
on_attach = on_attach,
|
||||
settings = { powershell = { scriptAnalysis = { settingsPath = custom_settings_path } } }
|
||||
}
|
||||
```
|
||||
|
||||
#### Autocomplete Brackets Troubleshooting
|
||||
If you're using `blink.cmp` and you're getting brackets when autocompleting
|
||||
cmdlet names, you'll need to add `{ "ps1", "psm1" }` to the blocked filetypes
|
||||
for both `kind_resolution` and `semantic_token_resolution` in the plugin's
|
||||
config file.
|
||||
|
||||
[Blink.cmp completion reference](https://cmp.saghen.dev/configuration/reference#completion-accept)
|
||||
|
||||
### Indentation
|
||||
|
||||
Vim/Neovim does not contain default `:h indentexpr` for filetype `ps1`.
|
||||
So you might notice indentation on newline is not behaving as expected for powershell files.
|
||||
Luckily powershell has similar syntax like C, so we can use `:h cindent` to fix the indentation problem.
|
||||
You can use the following snippet to either callback of an autocmd or ftplugin.
|
||||
|
||||
```lua
|
||||
--- ./nvim/lua/ftplugin/ps1.lua
|
||||
|
||||
-- disable indent from powershell treesitter parser
|
||||
-- because the parse isn't mature currently
|
||||
-- you can ignore this step if don't use treesitter
|
||||
if pcall(require, 'nvim-treesitter') then
|
||||
vim.schedule(function() vim.cmd([[TSBufDisable indent]]) end)
|
||||
end
|
||||
|
||||
vim.opt_local.cindent = true
|
||||
vim.opt_local.cinoptions:append { 'J1', '(1s', '+0' } -- see :h cino-J, cino-(, cino-+
|
||||
|
||||
vim.opt_local.iskeyword:remove { '-' } -- OPTIONALLY consider Verb-Noun as a whole word
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue