From 56a2624fc2425a82374895d5069c876967fdd7fc Mon Sep 17 00:00:00 2001 From: Alex Carney Date: Fri, 17 May 2024 19:32:51 +0100 Subject: [PATCH] chore: update pygls-playground README --- .vscode/extensions/pygls-playground/README.md | 45 ++++++++++++++++--- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/.vscode/extensions/pygls-playground/README.md b/.vscode/extensions/pygls-playground/README.md index 56d722b3..772699d4 100644 --- a/.vscode/extensions/pygls-playground/README.md +++ b/.vscode/extensions/pygls-playground/README.md @@ -38,7 +38,7 @@ Open terminal in the same directory as this file and execute following commands: 1. Install node dependencies ``` - npm install + npm install --no-save ``` 1. Compile the extension @@ -49,9 +49,14 @@ Open terminal in the same directory as this file and execute following commands: ### Run Extension (VSCode v1.89+) +> [!IMPORTANT] +> In order for VSCode to recognise `pygls-playground` as a valid extension, you need to complete the setup steps above **before** opening this repo inside VSCode. +> If you opened VSCode before compiling the extension, you will have to run the `Developer: Reload Window` command through the command palette (`Ctrl+Shift+P`) + 1. Open the `pygls` repository in VSCode -1. Goto the `Extensions` tab (`Ctrl+Shift+X`), find the `pygls-playground` extension in the *Recommended* section and click the `Install Workspace Extension` button +1. Goto the `Extensions` tab (`Ctrl+Shift+X`), find the `pygls-playground` extension in the *Recommended* section (not by searching in the marketplace!) and click the `Install Workspace Extension` button. + **If the button only says "Install", you've not found the right version of this extension** 1. You will need to make sure that VSCode is using a virtual environment that contains an installation of `pygls`. The `Python: Select Interpreter` command can be used to pick the correct one. @@ -74,25 +79,51 @@ Open terminal in the same directory as this file and execute following commands: Alternatively, you can set the `pygls.server.pythonPath` option in the `.vscode/settings.json` file +## Configuration + +By default, the `pygls-playground` extension is configured to run the example `code_actions.py` server which you can find in the `examples/servers` folder of this repository. +(For best results, try opening the `examples/servers/workspace/sums.txt` file). + +However, the `.vscode/settings.json` file in this repository can be used alter this and more. + +### Selecting a server + +> [!TIP] +> See the [README](../../../examples/servers/README.md) in the `examples/servers` folder for details on the available servers and which files they work best with. + +To select a different example server, change the `pygls.server.launchScript` setting to the name of the server you wish to run -#### Selecting the document language +### Selecting the working directory -The default settings for the `pygls-playground` VSCode extension are configured for the `json_server.py` example. In particular the server will only be used for `.json` files. +> [!TIP] +> Cryptic `Error: spawn /.../python ENOENT` messages are often due to the extension using an incorrect working directory. -The `code_actions.py` example is intended to be used with text files (e.g. the provided `sums.txt` file). To use the server with text files change the **Pygls > Client: Document Selector** setting to the following: +If everything works as expected, the `pygls-playground` extension **should** default to using the `examples/servers/` folder as its working directory. + +If this is not the case, or you want to change it to something else, you can change the `pygls.server.cwd` option + +### Selecting documents + +Language servers typically specialise in a relatively small number of file types, so a client will only ask a server about documents + +The `code_actions.py` example is intended to be used with `plaintext` files (e.g. the provided `sums.txt` file). To use a server with different file types you can modify the `pygls.client.documentSelector` option + +For example to use a server with `json` files: ``` "pygls.client.documentSelector": [ { "scheme": "file", - "language": "plaintext" + "language": "json" }, ], ``` You can find the full list of known language identifiers [here](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers). -#### Debugging the server +See the [LSP Specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#documentFilter) for details on all the available options that can be passed to the `pygls.client.documentSelector` option. + +### Debugging the server To debug the language server set the `pygls.server.debug` option to `true`. The server should be restarted and the debugger connect automatically.