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

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]

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

Ah, sorry I misunderstood 😃

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