Update and re-organise documentation

[alcarney]

Description (e.g. "Related to ...", etc.)

The existing user guide is an odd mismatch of information that is also, in places, inaccurate (e.g. #569).

This PR breaks the user guide up into separate more focused articles which (hopefully!) is easier to navigate, while simultaneously updating the information in line with v2. Rather than wait for perfect, some of these articles will be not written/incomplete but we should be able to pick these off over time

Closes #569

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

Automated linters

You can run the lints that are run on CI locally with:

uv run --all-extras poe lint

[tombh]

Nice. I checked out https://pygls--572.org.readthedocs.build/en/572/ too and it looks good.

[alcarney]

Thanks!