Ressurrect our pyodide support

.github/workflows/ci.yml

@@ -35,9 +35,9 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Use Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         id: setup-python
         with:
           python-version: ${{ matrix.python-version }}
@@ -53,7 +53,7 @@ jobs:
 
       - name: Load cached venv
         id: cached-poetry-dependencies
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: .venv
           key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
@@ -66,43 +66,56 @@ jobs:
           poe test
 
   test-pyodide:
-    needs: pre_job
+    needs: [pre_job, build]
     if: needs.pre_job.outputs.should_skip != 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - name: Use Python "3.10"
-        uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+
+      - uses: 'actions/setup-node@v4'
+        with:
+          node-version: 20.x
+          cache: 'npm'
+          cache-dependency-path: 'tests/pyodide/package-lock.json'
+
+      - id: setup-python
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.x"
+
       - name: Install Poetry
         uses: snok/install-poetry@v1
         with:
           virtualenvs-in-project: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-artifacts
+          path: 'dist'
+
       - name: Install Dependencies
-        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
         run: |
-          poetry install --with pyodide
-      - name: Run Testsuite
-        uses: nick-fields/retry@v2
-        with:
-          timeout_minutes: 10
-          max_attempts: 6
-          command: |
-            source $VENV
-            poe test-pyodide || true
+          poetry install --with test
+
+          cd tests/pyodide
+          npm ci
+
+      - name: Run tests
+        run: |
+          source $VENV
+          poe test-pyodide
 
   lint:
     needs: pre_job
     if: needs.pre_job.outputs.should_skip != 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Use Python
         id: use-python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
       - name: Install Poetry
@@ -113,7 +126,7 @@ jobs:
         # I wonder if we can replace this whole step with with the "Use Python" step above's `cache` field?
         # See: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#outputs-and-environment-variables
         id: cached-poetry-dependencies
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: .venv
           key: venv-${{ hashFiles('**/poetry.lock') }}-${{ steps.use-python.outputs.python-version }}
@@ -130,11 +143,11 @@ jobs:
     if: needs.pre_job.outputs.should_skip != 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Use Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
       - name: Install Poetry
@@ -143,7 +156,7 @@ jobs:
           virtualenvs-in-project: true
       - name: Load cached venv
         id: cached-poetry-dependencies
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: .venv
           key: venv-${{ hashFiles('**/poetry.lock') }}
@@ -155,7 +168,7 @@ jobs:
           git describe --tags --abbrev=0
           poetry build
       - name: Upload builds
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: build-artifacts
           path: "dist/*"

docs/source/clients/index.rst

@@ -0,0 +1,2 @@
+Coming Soon\ :sup:`TM`
+======================

docs/source/conf.py

@@ -69,6 +69,7 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
+    "pyodide": ("https://pyodide.org/en/stable", None),
 }
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/contributing/howto.rst

@@ -0,0 +1,7 @@
+How To
+======
+
+.. toctree::
+   :glob:
+
+   Run the Pyodide Tests <howto/run-pyodide-test-suite>

docs/source/contributing/howto/run-pyodide-test-suite.rst

@@ -0,0 +1,95 @@
+How To Run the Pyodide Test Suite
+=================================
+
+.. highlight:: none
+
+This guide outlines how to setup the environment needed to run the `Pyodide <https://pyodide.org/en/stable/>`__ test suite.
+
+#. If you haven't done so already, install ``pytest`` and the other testing dependencies using poetry::
+
+     $ poetry install --with test
+
+#. In order to run Pyodide outside of the browser you will need `NodeJs <https://nodejs.org/en>`__ installed.
+
+#. Additionaly you will need to install the required node dependencies (which are specified in ``tests/pyodide/package.json``)::
+
+     $ cd tests/pyodide
+     tests/pyodide $ npm ci
+
+#. To bootstrap the Python environment within the Pyodide runtime the test suite needs to install ``pygls`` from its wheel archive.
+   From the repository root, use poetry to package the current development version::
+
+     $ poetry build
+
+   This will place the required ``*.whl`` file in the ``dist/`` folder
+
+#. Finally, to run the end-to-end tests against Pyodide, pass the ``--lsp-runtime pyodide`` option to ``pytest``::
+
+     $ poetry run pytest --lsp-runtime pyodide
+     ============================================ test session starts ============================================
+     platform linux -- Python 3.13.0, pytest-8.3.3, pluggy-1.5.0
+     rootdir: /var/home/alex/Projects/openlawlibrary/pygls/main
+     configfile: pyproject.toml
+     plugins: cov-5.0.0, asyncio-0.24.0
+     asyncio: mode=Mode.AUTO, default_loop_scope=None
+     pygls: runtime='pyodide', transport='stdio'
+     collected 216 items
+
+     tests/e2e/test_code_action.py .                                                                        [  0%]
+     tests/e2e/test_code_lens.py ...                                                                        [  1%]
+     tests/e2e/test_colors.py ..                                                                            [  2%]
+     tests/e2e/test_completion.py .                                                                         [  3%]
+     tests/e2e/test_declaration.py .                                                                        [  3%]
+     tests/e2e/test_definition.py .                                                                         [  4%]
+     tests/e2e/test_formatting.py ....                                                                      [  6%]
+     tests/e2e/test_hover.py ...                                                                            [  7%]
+     tests/e2e/test_implementation.py .                                                                     [  7%]
+     tests/e2e/test_inlay_hints.py .                                                                        [  8%]
+     tests/e2e/test_links.py ..                                                                             [  9%]
+     tests/e2e/test_publish_diagnostics.py .                                                                [  9%]
+     tests/e2e/test_pull_diagnostics.py ...                                                                 [ 11%]
+     tests/e2e/test_references.py .                                                                         [ 11%]
+     tests/e2e/test_rename.py ....                                                                          [ 13%]
+     tests/e2e/test_semantic_tokens.py ......                                                               [ 16%]
+     tests/e2e/test_symbols.py ...                                                                          [ 17%]
+     tests/e2e/test_threaded_handlers.py .ss                                                                [ 18%]
+     tests/e2e/test_type_definition.py .                                                                    [ 19%]
+     tests/lsp/test_call_hierarchy.py .....                                                                 [ 21%]
+     tests/lsp/test_document_highlight.py ...                                                               [ 23%]
+     tests/lsp/test_errors.py .....                                                                         [ 25%]
+     tests/lsp/test_folding_range.py ...                                                                    [ 26%]
+     tests/lsp/test_linked_editing_range.py ...                                                             [ 28%]
+     tests/lsp/test_moniker.py ...                                                                          [ 29%]
+     tests/lsp/test_progress.py .......                                                                     [ 32%]
+     tests/lsp/test_selection_range.py ...                                                                  [ 34%]
+     tests/lsp/test_signature_help.py .ss                                                                   [ 35%]
+     tests/lsp/test_type_hierarchy.py .....                                                                 [ 37%]
+     tests/test_client.py ...                                                                               [ 39%]
+     tests/test_document.py .......................                                                         [ 50%]
+     tests/test_feature_manager.py .......................................                                  [ 70%]
+     tests/test_language_server.py .......                                                                  [ 73%]
+     tests/test_protocol.py ....................                                                            [ 82%]
+     tests/test_server_connection.py ...                                                                    [ 84%]
+     tests/test_types.py ...                                                                                [ 85%]
+     tests/test_uris.py .......sssss                                                                        [ 91%]
+     tests/test_workspace.py ...................                                                            [100%]
+     ================================ 207 passed, 9 skipped in 102.04s (0:01:42) =================================
+
+
+.. tip::
+
+   You can find logs from the Pyodide environment in a file called ``pyodide.log`` in the repository root::
+
+     $ tail -f
+     Loading micropip, packaging
+     Loaded micropip, packaging
+     Loading attrs, six
+     Loaded attrs, six
+     Starting sync IO server
+     Language server initialized InitializeParams(capabilities=ClientCapabilities(workspace=None, text_document=None, notebook_document=None, window=None, general=None, experimental=None), process_id=None, client_info=None, locale=None, root_path=None, root_uri='file:///workspace', initialization_options=None, trace=None, work_done_token=None, workspace_folders=None)
+     Sending data: {"id": "5f4b70c6-fd2f-4806-985c-ce059c6a1c38", "jsonrpc": "2.0", "result": {"capabilities": {"positionEncoding": "utf-16", "textDocumentSync": {"openClose": true, "change": 2, "save": false}, "declarationProvider": true, "definitionProvider": true, "typeDefinitionProvider": true, "implementationProvider": true, "referencesProvider": true, "executeCommandProvider": {"commands": []}, "workspace": {"workspaceFolders": {"supported": true, "changeNotifications": true}, "fileOperations": {}}}, "serverInfo": {"name": "goto-server", "version": "v1"}}}
+     Index: {'file:///workspace/code.txt': {'types': {'Rectangle': 0:5-0:14, 'Square': 1:5-1:11}, 'functions': {'area': 3:3-3:7, 'volume': 5:3-5:9}}}
+     Sending data: {"id": "f61d6b6a-9dab-4c56-b2c4-f751bfbb52da", "jsonrpc": "2.0", "result": null}
+     Sending data: {"id": "db8b8009-adca-4b48-86a5-b04b622d6426", "jsonrpc": "2.0", "result": {"uri": "file:///workspace/code.txt", "range": {"start": {"line": 0, "character": 5}, "end": {"line": 0, "character": 14}}}}
+     Sending data: {"id": "e6de9938-5af2-45bf-a730-19e29e6a0465", "jsonrpc": "2.0", "result": null}
+     Shutting down the server

docs/source/index.rst

@@ -10,20 +10,45 @@ allows you to write your own `language server`_ in just a few lines of code
 
 *pygls* supports
 
-- Python 3.8+ on Windows, MacOS and Linux
+- Python 3.9+ on Windows, MacOS and Linux
+- **Experimental** support for Pyodide
 - STDIO, TCP/IP and WEBSOCKET communication
 - Both sync and async styles of programming
 - Running code in background threads
 - Automatic text and notebook document syncronisation
 
 .. toctree::
    :hidden:
-   :caption: User Guide
+   :caption: Language Servers
 
-   getting-started
-   user-guide
-   How To <howto>
-   reference
+   servers/getting-started
+   servers/user-guide
+   How To <servers/howto>
+
+.. toctree::
+   :hidden:
+   :caption: Language Clients
+
+   clients/index
+
+.. toctree::
+   :hidden:
+   :caption: The Protocol
+
+   protocol/howto
+
+.. toctree::
+   :hidden:
+   :caption: The Library
+
+   pygls/howto
+   pygls/reference
+
+.. toctree::
+   :hidden:
+   :caption: Contributing
+
+   contributing/howto
 
 .. toctree::
    :hidden:
@@ -33,34 +58,54 @@ allows you to write your own `language server`_ in just a few lines of code
    history
    changelog
 
+Navigation
+----------
+
+*The pygls documentation tries to (with varying degrees of success!) follow the* `Diátaxis <https://diataxis.fr/>`__ *approach to writing documentation*
 
-The documentation is divided up into the following sections
+This documentation site is divided up into the following sections
 
 .. grid:: 1 2 2 2
    :gutter: 2
 
-   .. grid-item-card:: Getting Started
-      :link: /getting-started
+   .. grid-item-card:: Language Servers
+      :link: servers/getting-started
       :link-type: doc
       :text-align: center
 
-      First steps with *pygls*.
+      Documentation specific to implementing Language Servers using *pygls*.
+
+   .. grid-item-card:: Language Clients
+      :text-align: center
+
+      Documentation specific to implementing Language Clients using *pygls*.
+      Coming Soon\ :sup:`TM`!
 
-   .. grid-item-card:: How To Guides
-      :link: /howto
+   .. grid-item-card:: The Protocol
+      :link: protocol/howto
       :link-type: doc
       :text-align: center
 
-      Short, focused articles on how to acheive a particular outcome
+      Additional articles that explain some aspect of the Language Server Protocol in general.
 
-   .. grid-item-card:: API Reference
-      :link: /reference
+   .. grid-item-card:: The Library
+      :link: pygls/howto
       :link-type: doc
-      :columns: 12
       :text-align: center
 
-      Comprehensive, detailed documentation on all of the features provided by *pygls*.
+      Documentation that applies to the *pygls* library itself e.g. migration guides.
+
+   .. grid-item-card:: Contributing
+      :link: contributing/howto
+      :link-type: doc
+      :text-align: center
+
+      Guides on how to contribute to *pygls*.
+
+   .. grid-item-card:: About
+      :text-align: center
 
+      Additional context on the *pygls* project.
 
 .. _Language Server Protocol: https://microsoft.github.io/language-server-protocol/specification
 .. _Language server: https://langserver.org/

docs/source/protocol/howto.rst

@@ -0,0 +1,8 @@
+How To
+======
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   Interpret Semantic Tokens <howto/interpret-semantic-tokens>