chore: update pygls-playground README

.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.