Update description on how to edit plugins

[marimeireles]

References

#417

Code changes

Just fix the comments for people using it as a reference.

Backwards-incompatible changes

None

Chores

• [ ] linted
• [ ] tested
• [ ] documented
• [ ] changelog entry

[krassowski]

Maybe we should forbid any top keys different from language_servers? This would at least shown an error (in the bottom-right corner). Right now it accepts everything which is indeed error-prone.

[krassowski]

@bollwyvl any thoughts?

[bollwyvl]

I don't know what else we'd like to land in here, (e.g. debug, etc.), but making a schema more restrictive (e.g. removing additionalProperties: true) after the fact is painful, and would probably require a hard version bump. There's also no in-UI way to do migrations, and the failure modes are gross when things don't work properly.

I also find the JSON5 "docs" all but worthless for anything other than bools, etc. We might be better off:

• making some docs, and pointing to those instead of the pyls-specific example
• adding a bespoke UI which manipulates the settings (with knowledge of the schema from the specs), and have a short doc, e.g. please open the Language Server Settings Pane with _Settings -> Language Servers

[krassowski]

Maybe we could add additional comment to clarify that pyls needs to go inside language_servers using description like in https://github.com/jupyterlab/jupyterlab/blob/272b7a40911a8f62f3ba225f0c8a8835ec6f5547/packages/shortcuts-extension/src/index.ts#L87-L106

[mlucool]

I like @bollwyvl idea of pointing to examples rather than inline here because it's not obvious what goes into language_servers and then you have more room for a lot of examples. I thought I could just copy/paste what was in // but that turned out to be wrong (see idea 2 below).

Other ideas:

1. If you find any language server outside of language_servers show the user an alert. This isn't all the way to removing additionalProperties: true, but hints they likely got it wrong. Maybe this is more complex than just making a small breaking release.
2. Repeat yourself more to make it copy/paste friendly.

    // Language Server
    // Language-server specific configuration, keyed by implementation, e.g: 
    // 
    // language_servers: {
    //   pyls: {
    //     serverSettings: {
    //       pyls: {
    //         plugins: {
    //           pydocstyle: {
    //             enabled: true
    //           },
    //           pyflakes: {
    //             enabled: false
    //           },
    //           flake8: {
    //             enabled: true
    //           }
    //         }
    //       }
    //     }
    //   }
    // }
    // 
    // Alternatively, using VSCode's naming convention:
    // language_servers: {
    //   pyls: {
    //     serverSettings: {
    //       "pyls.plugins.pydocstyle.enabled": true,
    //       "pyls.plugins.pyflakes.enabled": false,
    //       "pyls.plugins.flake8.enabled": true
    //     }
    //   }
    // }
    "language_servers": {
        "pyright": {
            "serverSettings": {
                "python.analysis.useLibraryCodeForTypes": true
            }
        }
    },

[krassowski]

Closing in favour of the new configuration UI added in https://github.com/jupyter-lsp/jupyterlab-lsp/pull/778.