Include LSP spec docs next to command definitions (TEXT_DOCUMENT_DID_OPEN etc)

[tombh]

I think it'd be nice to include snippets of the official LSP docs next to the command definitions, eg;

TEXT_DOCUMENT_DID_OPEN = 'textDocument/didOpen'
"""
The document open notification is sent from the client to the server to signal
newly opened text documents. The document’s content is now managed by the client
and the server must not try to read the document’s content using the document’s Uri.
Open in this sense means it is managed by the client. It doesn’t necessarily mean
that its content is presented in an editor. An open notification must not be sent
more than once without a corresponding close notification send before. This means
open and close notification must be balanced and the max open count for a particular
textDocument is one. Note that a server’s ability to fulfill requests is independent
of whether a text document is open or closed.

https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_didOpen
"""

It's a lot of work, and they'll relatively easily go out of date. But I wonder if it's better to include them, even if they do get stale, than to have nothing at all. The URL to the specific paragraph at least has the associated LSP spec version.

It's also worth noting the docs can't really be copied wholesale, because Pygls hides a lot of implementation details that Pygls users should not be concerned with. And hence a bit of curation is needed when adding the relevant docs to Pygls.

It looks like we'll get equivalent documentation for types automatically when lsprotocol support is merged (#264). So that'll cover that side of the spec.

What are you thoughts? Is this the best place to put the command docs? Is the only sticking point the sheer grunt work of adding and maintaining them?

[alcarney]

I think having a summary of what's available and how to reference it in Python would be a great addition to the pygls docs.
I'm sure it would even be possible to add a small extension to Sphinx to automate it - assuming the snippets we want are easily accessible via the types in lsprotocol

[tombh]

Great, thanks for the feedback. Wow, I hadn't that about how Sphinx cold automate that. Could you very briefly describe how it would do that? As in, it would be automated within the editor, like a shortcut to prepopulate from the relevant LSP text, then I would be able to edit/curate it a little before committing it?

[alcarney]

I guess it depends on what workflow you want, Sphinx is flexible enough you can basically do what you like.

On the one end of the spectrum you don’t even have to touch Sphinx and write a script that spits out a bunch of rst files using the standard python syntax to document the LSP methods etc.

Or you could go to the opposite end and implement a custom directive letting you put a single

.. autolspdoc:: 

in an rst file and have the docs be written automagically during the build.

[tombh]

Ah right, you're talking about taking the comments (those which this issue is proposing to write) being copied to the website docs? Yes, that's a great idea too.

I thought you might have meant that Sphinx could somehow parse the LSP spec docs and automatically update the Pygls comments/docs from them. But I'm not even sure any tool could do that.

[alcarney]

Ah right, you're talking about taking the comments (those which this issue is proposing to write)

Ah, sorry I misunderstood :)