Where to put structured documentation now?

[krassowski]

Now removed vscode-client had package.json which included a structured documentation of configuration options. Should we retain this file (possibly in a different place/under a different name)?

[krassowski]

We do not need entire file, and it probably should not be named package.json any longer. The lines that would be useful to keep: https://github.com/palantir/python-language-server/blob/a91a257d2c8687a7931721d387b2ffeb6aa71fc2/vscode-client/package.json#L19-L297

[andfoy]

I think we should probably have a separate configuration markdown document in the repo

[krassowski]

Markdown is nice because it is human-readable but not nice if you ever decide to make a GUI for pylsp settings. I was thinking about preserving the JSON structure for that reason. Maybe we could auto-generate a markdown file or sphinx docs out of such JSON for readability?

[andfoy]

I think we could have a sample-configuration.json with the actual server configuration.

Maybe the documentation could be similar to the one we use in https://github.com/spyder-ide/pyls-spyder that describes the keys and sections and which hookspecs use them.

[ccordoba12]

I agree with @andfoy's suggestion.

[raprocks]

Any progress on this? If anyone is not pursuing this maybe someone can point me in some direction so that i can work on it? also we can possibly keep both a json and a markdown format so that we get the best of both worlds haha.

[krassowski]

I would say let's generate markdown from JSON and keep JSON as the source of truth. Feel free to work on this is you like :)

[raprocks]

well how do i find all the settings that this lsp provides? any references?

[krassowski]

Here:
https://github.com/palantir/python-language-server/blob/a91a257d2c8687a7931721d387b2ffeb6aa71fc2/vscode-client/package.json#L19-L297

[raprocks]

Oh thanks will take a look at that