Update documentation

[alcarney]

As highlighted in #424, our tutorial is a bit out of date and could do with a refresh.

This PR takes the opportunity to update the documentation as a whole, re-organizing it so that it's hopefully easier to navigate. I'm also porting some of the examples that are buried in our issues so that they are easier to find.

I'm using the Diátaxis documentation framework as a guide

TODO

• Update/rewrite tutorial
• Guide on handling invalid data (Be less strict with wrong LSP types? #326 (comment))

Code review checklist (for code reviewer to complete)

• Pull request represents a single change (i.e. not fixing disparate/unrelated things in a single PR)
• Title summarizes what is changing
• Commit messages are meaningful (see this for details)
• Tests have been included and/or updated, as appropriate
• Docstrings have been included and/or updated, as appropriate
• Standalone docs have been updated accordingly

[alcarney]

@tombh are you able to enable pr builds for readthedocs?

[tombh]

I don't yet. I message David about it.

[tombh]

David said that it should be enabled now.

[alcarney]

Hmm, it does not appear to be working... I'd expect to see a readthedocs item to appear in the list of CI checks and it be linked to a build of the docs generated from this PR 🤔

[tombh]

Ah 😬 Okay, I've let David know.

[tombh]

You should have an invite to join the readthedocs.io account.

[alcarney]

I don't see anything wrong in the config... though the docs suggest that resync-ing the webhook might fix it - something that I don't have permission (in GitHub) todo.

[tombh]

The "Pull requests" toggle wasn't set:

So I set it. Does that fix it?

[alcarney]

Does that fix it?

Yes! Thank you 😄

You can now click the Details link on the readthedocs check to see a preview of what this PR will do if merged

[noklam]

Would love to see more example of implementations. For example I am looking for how to implement "find reference". I find Jedi's example: https://github.com/pappasam/jedi-language-server/blob/9df0ab5c3481c4e637a8cc1dc3bb5e7afb11c960/jedi_language_server/server.py#L414C1-L428C44

What's the plan or guideline around adding new examples? I may be able to contribute back an example or two later. I think the library is awesome but it's hard to get started with it. Often, I need to look at other libraries source code instead of the docs.

[alcarney]

Have you found our example servers? You can find an example of find references here. Though I admit we don't currently have any prose to explain what is going on.

What's the plan or guideline around adding new examples?

I'd like to convert all of the tests here to end to end tests like these, where each test is backed by a corresponding example server. #440 was the first pass at this and I'm currently working on an example server for the various document formatting methods.

I may be able to contribute back an example or two later.

If you can, that would be awesome :)

I think the library is awesome but it's hard to get started with it

I agree, hopefully, slowly but surely we can turn that around :)

[noklam]

@alcarney Thanks, I did see the example but somehow missed the find_reference part.

I think one thing that I struggle with is that I don't know how to map the server protocol to something that I can see in an IDE (VSCode). I understand pygls is not only for VSCode. For example what does Go to Reference and Find all reference correspond to? This is not necessary problem of pygls, probably more of VSCode documentation problem. Googling doesn't give me anything immediate useful. I usually have to try the example server, find a way to trigger the code and see it in action to understand what does it actually do.

This example servers is amazing btw, it has the backbone of everything I needed. Thanks again!

If you can, that would be awesome :)

For sure, let me know if there is anything I can help, like reviewing the documentation or testing it.

[noklam]

https://github.com/microsoft/vscode-extension-samples/tree/main/completions-sample

came across this and I find this is quite helpful.

[alcarney]

@tombh would you be ok with merging this PR as is?

It's not going to be perfect, but I think this is in a place now where we can start adding to it incrementally

[tombh]

Sure! I had a look at https://pygls--427.org.readthedocs.build/en/427/ and it looks great!

[alcarney]

Thanks!