openlawlibrary · alcarney · Jul 20, 2025 · Jul 19, 2025 · Jul 17, 2025 · Jul 17, 2025
diff --git a/Makefile b/Makefile
@@ -14,7 +14,7 @@ docs: docs/requirements.txt | $(UV)
 	$(UV) run --group docs sphinx-build -M html docs/source docs/build
 
 docs/requirements.txt: uv.lock | $(UV)
-	$(UV) export --format requirements.txt --no-emit-project  --group docs --output-file $@
+	$(UV) export --format requirements.txt --all-extras --no-emit-project --no-default-groups --group docs --output-file $@
 
 .PHONY: lint
 lint: | $(UV)

diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -22,8 +22,8 @@ allows you to write your own `language server`_ in just a few lines of code
    :caption: Language Servers
 
    servers/getting-started
-   servers/user-guide
    How To <servers/howto>
+   servers/reference
 
 .. toctree::
    :hidden:
@@ -43,6 +43,7 @@ allows you to write your own `language server`_ in just a few lines of code
 
    pygls/howto
    pygls/reference
+   pygls/api-reference
 
 .. toctree::
    :hidden:

diff --git a/docs/source/pygls/api-reference.rst b/docs/source/pygls/api-reference.rst
@@ -0,0 +1,63 @@
+Python API
+==========
+
+In this section you will find reference documentation on pygls' Python API
+
+.. toctree::
+   :hidden:
+   :glob:
+
+   api-reference/*
+
+
+.. grid:: 1 2 2 2
+   :gutter: 2
+
+   .. grid-item-card:: Clients
+      :link: api-reference/clients
+      :link-type: doc
+      :text-align: center
+
+      pygls' Language Client APIs.
+
+   .. grid-item-card:: Servers
+      :link: api-reference/servers
+      :link-type: doc
+      :text-align: center
+
+      pygls' Language Server APIs
+
+   .. grid-item-card:: LSP Types
+      :link: api-reference/types
+      :link-type: doc
+      :text-align: center
+
+      LSP type definitions, as provided by the *lsprotocol* library
+
+   .. grid-item-card:: URIs
+      :link: api-reference/types
+      :link-type: doc
+      :text-align: center
+
+      Helper functions for working with URIs
+
+   .. grid-item-card:: Workspace
+      :link: api-reference/workspace
+      :link-type: doc
+      :text-align: center
+
+      pygls' workspace API
+
+   .. grid-item-card:: Protocol
+      :link: api-reference/protocol
+      :link-type: doc
+      :text-align: center
+
+      pygls' low-level protocol APIs
+
+   .. grid-item-card:: IO
+      :link: api-reference/io
+      :link-type: doc
+      :text-align: center
+
+      pygls' low-level input/output APIs
diff --git a/docs/source/pygls/reference/clients.rst → docs/source/pygls/api-reference/clients.rst b/docs/source/pygls/reference/clients.rst → docs/source/pygls/api-reference/clients.rst
diff --git a/docs/source/pygls/reference/io.rst → docs/source/pygls/api-reference/io.rst b/docs/source/pygls/reference/io.rst → docs/source/pygls/api-reference/io.rst
diff --git a/docs/source/pygls/reference/protocol.rst → docs/source/pygls/api-reference/protocol.rst b/docs/source/pygls/reference/protocol.rst → docs/source/pygls/api-reference/protocol.rst
diff --git a/docs/source/pygls/reference/servers.rst → docs/source/pygls/api-reference/servers.rst b/docs/source/pygls/reference/servers.rst → docs/source/pygls/api-reference/servers.rst
@@ -3,6 +3,10 @@ Servers
 
 .. autoclass:: pygls.lsp.server.LanguageServer
    :members:
+   :inherited-members:
+
+
+.. autofunction:: pygls.cli.start_server
 
 .. autoclass:: pygls.progress.Progress
    :members:

diff --git a/docs/source/pygls/reference/types.rst → docs/source/pygls/api-reference/types.rst b/docs/source/pygls/reference/types.rst → docs/source/pygls/api-reference/types.rst
diff --git a/docs/source/pygls/reference/uris.rst → docs/source/pygls/api-reference/uris.rst b/docs/source/pygls/reference/uris.rst → docs/source/pygls/api-reference/uris.rst
diff --git a/docs/source/pygls/reference/workspace.rst → .../source/pygls/api-reference/workspace.rst b/docs/source/pygls/reference/workspace.rst → .../source/pygls/api-reference/workspace.rst
diff --git a/docs/source/pygls/howto.rst b/docs/source/pygls/howto.rst
@@ -7,3 +7,6 @@ How To
 
    Migrate to v1 <howto/migrate-to-v1>
    Migrate to v2 <howto/migrate-to-v2>
+   Send Custom Messages <howto/send-custom-messages>
+   Use Custom Converter <howto/use-custom-converter>
+   Use the pygls-playground <howto/use-the-pygls-playground>
diff --git a/docs/source/pygls/howto/migrate-to-v2.rst b/docs/source/pygls/howto/migrate-to-v2.rst
@@ -1,10 +1,6 @@
 How To Migrate to v2.0
 ======================
 
-.. note::
-
-   This guide is still a draft, some details may change
-
 The highlight of the *pygls* v2 release is upgrading ``lsprotocol`` to ``v2024.x`` bringing with it support for the proposed LSP v3.18 types and methods.
 The new version includes standardised object names (so no more classes like ``NotebookDocumentSyncRegistrationOptionsNotebookSelectorType2CellsType``!)
 
@@ -13,6 +9,12 @@ This guide outlines how to adapt an existing server to the breaking changes intr
 
 **Known Migrations**
 
+.. admonition:: Finished your migration?
+   :class: tip
+
+   Have you migrated your server to ``v2``?
+   Feel free to open a pull request and add yours to the list below!
+
 You may find these projects that have already successfully migrated to v2 a useful reference:
 
 - Our `example servers <https://github.com/openlawlibrary/pygls/commit/e90f88ad642a20d3a16551e00a5a0abe0a1e041f>`__
@@ -22,7 +24,10 @@ You may find these projects that have already successfully migrated to v2 a usef
 Python Support
 --------------
 
-*pygls v2* removes support for Python 3.8 and adds support for Python 3.13 (with the GIL, you are welcome to try the free-threaded version just note that it has not been tested yet!)
+*pygls v2*
+
+- Removes support for Python 3.8
+- Adds support for Python 3.13 and 3.14 (with the GIL, you are welcome to try a free-threaded build just note that it has not been tested yet!)
 
 URI Handling
 ------------
@@ -52,6 +57,24 @@ The following methods and functions have been deprecated for some time and have
 ``Worspace.update_document``                        ``Workspace.update_text_document``
 ==================================================  ==============
 
+Sending Custom Notifications
+----------------------------
+
+The ``send_notification`` method on the ``LanguageServer`` has been removed without a prior deprecation notice (sorry!)
+
+To send custom notifications in v2, use the ``notify`` method on the underlying protocol object.
+
+.. code-block:: python
+
+   # Before
+   server.send_notification("my/customNotification", {"example": "data"})
+
+   # After
+   server.protocol.notify("my/customNotification", {"example": "data"})
+
+See :ref:`howto-send-custom-messages` for more details
+
+
 Server commands can now use type annotations
 --------------------------------------------
 

diff --git a/docs/source/pygls/howto/send-custom-messages.rst b/docs/source/pygls/howto/send-custom-messages.rst
@@ -0,0 +1,94 @@
+.. _howto-send-custom-messages:
+
+How To Send Custom Messages
+===========================
+
+
+.. admonition:: Work in Progress
+   :class: note
+
+   This guide needs more detail
+
+A custom notification can be sent to the client (or server) using the :meth:`~pygls.protocol.JsonRPCProtocol.notify` method of the underlying protocol object
+
+.. code-block:: python
+
+   server.protocol.notify('my/customNotification', {"example": "data"})
+
+Simiarly, the :meth:`~pygls.protocol.JsonRPCProtocol.send_request` and :meth:`~pygls.protocol.JsonRPCProtocol.send_request_async` methods can be used to send a custom request
+
+.. code-block:: python
+
+   response = client.protocol.send_request('my/customRequest', {"example": "data"})
+
+   response = await client.protocol.send_request_async('my/customRequest', {"example": "data"})
+
+Depending on your use case this may be sufficient however, you lose all typing information this way.
+It is possible to extend the :class:`~pygls.protocol.LanguageServerProtocol` object used by *pygls* (or in fact define a completely custom :class:`~pygls.protocol.JsonRPCProtocol`!)
+
+Extending ``LanguageServerProtocol``
+------------------------------------
+
+.. code-block:: python
+
+   from pygls.protocol import LanguageServerProtocol
+
+
+   class MyCustomExtension(LanguageServerProtocol):
+
+      def __init__(self, server: LanguageServer, converter: Converter):
+         super().__init__(server, converter)
+
+      def get_message_type(self, method: str) -> Type[Any] | None:
+         """Return my custom message types, falling back to ``LanguageServerProtocol``
+         where needed"""
+
+         if method == "my/customRequest":
+             return MyCustomRequest
+
+         return super().get_message_type(method)
+
+      def get_result_type(self, method: str) -> Type[Any] | None:
+         """Return my custom response types, falling back to ``LanguageServerProtocol``
+         where needed"""
+
+         if method == "my/customRequest":
+             return MyCustomResponse
+
+         return super().get_result_type(method)
+
+To use your custom protocol type, pass it to the :class:`~pygls.lsp.server.LanguageServer`
+
+.. code-block::
+
+   server = LanguageServer(
+       name="my-language-server",
+       version="v1.0",
+       protocol_cls=MyCustomExtension,
+   )
+
+Defining a Custom Protocol
+--------------------------
+
+A similar approach is needed to define an entirely custom JSON-RPC protocol
+
+.. code-block:: python
+
+   from pygls.protocol import JsonRPCProtocol, default_converter
+   from pygls.server import JsonRPCServer
+
+   class MyCustomProtocol(JsonRPCProtocol):
+
+      def __init__(self, server: LanguageServer, converter: Converter):
+         super().__init__(server, converter)
+
+      def get_message_type(self, method: str) -> Type[Any] | None:
+          ...
+
+      def get_result_type(self, method: str) -> Type[Any] | None:
+          ...
+
+   server = JsonRPCServer(
+       protocol_cls=MyCustomProtocol,
+       converter_factory=default_converter,
+   )
diff --git a/...rce/servers/howto/handle-invalid-data.rst → ...urce/pygls/howto/use-custom-converter.rst b/...rce/servers/howto/handle-invalid-data.rst → ...urce/pygls/howto/use-custom-converter.rst
@@ -1,9 +1,34 @@
-How To Handle Invalid Data
-==========================
+.. _howto-use-custom-converter:
+
+How To Use a Custom Converter
+=============================
+
+.. admonition:: Help Wanted
+   :class: tip
+
+   This page needs reworking slightly, it currently gives an approach for handling invalid data, but it should also be made clear that this approach can also be used to handle custom data types.
+
+``pygls`` relies on `lsprotocol <https://github.com/microsoft/lsprotocol/>`__ for all of its type definitions.
+``lsprotocol`` in turn builds on `attrs <https://www.attrs.org/en/stable/>`__ and `cattrs <https://catt.rs/en/stable/>`__ to provide the serialisation and deserialisation of types to/from JSON.
+
+This is done through a ``converter`` object::
+
+   >>> from lsprotocol.types import Position
+   >>> from pygls.protocol import default_converter
+
+   >>> converter = default_converter()
+   >>> p = converter.structure({"line": 1, "character": 2}, Position)
+   >>> p.line
+   1
+   >>> p.character
+   2
+
+Each language client/server receives a :func:`~pygls.protocol.default_converter` which is derived from the converter provided by ``lsprotocol``.
+This means it will follow the Language Server Protocol exactly.
 
 .. highlight:: python
 
-By default, servers written with *pygls* are quite pedantic and will complain loudly when given data they consider to be invalid
+Therefore, clients/servers written with *pygls* are pedantic and will complain loudly when given data they consider to be invalid
 
 .. dropdown:: Example Data
    :open:
@@ -95,24 +120,6 @@ By default, servers written with *pygls* are quite pedantic and will complain lo
          ...
       pygls.exceptions.JsonRpcInvalidParams: Invalid Params
 
-This is due to the fact ``pygls`` relies on `lsprotocol <https://github.com/microsoft/lsprotocol/>`__ for all of its type definitions.
-``lsprotocol`` in turn builds on `attrs <https://www.attrs.org/en/stable/>`__ and `cattrs <https://catt.rs/en/stable/>`__ to provide the serialisation and deserialisation of types to/from JSON.
-
-This is done through a ``converter`` object::
-
-   >>> from lsprotocol.types import Position
-   >>> from pygls.protocol import default_converter
-
-   >>> converter = default_converter()
-   >>> p = converter.structure({"line": 1, "character": 2}, Position)
-   >>> p.line
-   1
-   >>> p.character
-   2
-
-Each language server receives a :func:`~pygls.protocol.default_converter` which is derived from the converter provided by ``lsprotocol``.
-This means it will follow the Language Server Protocol exactly.
-
 Structure Hooks
 ---------------
 

diff --git a/...ervers/howto/use-the-pygls-playground.rst → .../pygls/howto/use-the-pygls-playground.rst b/...ervers/howto/use-the-pygls-playground.rst → .../pygls/howto/use-the-pygls-playground.rst
diff --git a/docs/source/pygls/reference.rst b/docs/source/pygls/reference.rst
@@ -1,63 +1,10 @@
-Python API
-==========
+Reference
+=========
 
-In this section you will find reference documentation on pygls' Python API
+In this section you will find reference documentation on aspects of *pygls* that aren't specific to language clients or servers.
 
 .. toctree::
-   :hidden:
-   :glob:
+   :maxdepth: 1
 
-   reference/*
-
-
-.. grid:: 1 2 2 2
-   :gutter: 2
-
-   .. grid-item-card:: Clients
-      :link: reference/clients
-      :link-type: doc
-      :text-align: center
-
-      pygls' Language Client APIs.
-
-   .. grid-item-card:: Servers
-      :link: reference/servers
-      :link-type: doc
-      :text-align: center
-
-      pygls' Language Server APIs
-
-   .. grid-item-card:: LSP Types
-      :link: reference/types
-      :link-type: doc
-      :text-align: center
-
-      LSP type definitions, as provided by the *lsprotocol* library
-
-   .. grid-item-card:: URIs
-      :link: reference/types
-      :link-type: doc
-      :text-align: center
-
-      Helper functions for working with URIs
-
-   .. grid-item-card:: Workspace
-      :link: reference/workspace
-      :link-type: doc
-      :text-align: center
-
-      pygls' workspace API
-
-   .. grid-item-card:: Protocol
-      :link: reference/protocol
-      :link-type: doc
-      :text-align: center
-
-      pygls' low-level protocol APIs
-
-   .. grid-item-card:: IO
-      :link: reference/io
-      :link-type: doc
-      :text-align: center
-
-      pygls' low-level input/output APIs
+   reference/logging
+   reference/message-handler-types