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

[yen3]

Thanks for the patch from #51. It lacks the descriptions and definitions for the 3rd Party Plugins. Where could I find? Thank you for your help.

[krassowski]

That's a good question. The obvious answer is that it's best to check in the repositories of respective third party plugins.

The less obvious possibility would be to ask all plugins to follow the same schema format and auto-generate one documentation file for all of them on CI. That would require the central repository to track the plugins (which is somehow already done by the means of linking to some of them). I don't know if this is manageable though.

[andfoy]

I think it is more feasible letting each plugin to publish their own configuration options, since we cannot handle all updates and it could be probably get outdated easily.