From 31cc529f6e77264861ede7a67a18ebf4815fa0b6 Mon Sep 17 00:00:00 2001 From: Alex Carney Date: Fri, 8 Sep 2023 13:39:44 +0100 Subject: [PATCH] docs: update links and code snippets --- docs/source/pages/getting_started.rst | 29 ++++++++++------------ docs/source/pages/testing.rst | 6 +---- docs/source/pages/tutorial.rst | 35 ++++++++++++++++----------- 3 files changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/source/pages/getting_started.rst b/docs/source/pages/getting_started.rst index d8286604..e73d20fa 100644 --- a/docs/source/pages/getting_started.rst +++ b/docs/source/pages/getting_started.rst @@ -6,12 +6,12 @@ servers that are based on it. .. note:: - Before going any further, if you are not familiar with *language servers* - and *Language Server Protocol*, we recommend reading following articles: + Before going any further, if you are not familiar with *language servers* + and *Language Server Protocol*, we recommend reading following articles: - - `Language Server Protocol Overview `_ - - `Language Server Protocol Specification `_ - - `Language Server Protocol SDKs `_ + - `Language Server Protocol Overview `_ + - `Language Server Protocol Specification `_ + - `Language Server Protocol SDKs `_ Installation @@ -23,12 +23,11 @@ To get the latest release from *PyPI*, simply run: pip install pygls -Alternatively, *pygls* source code can be downloaded from our `GitHub`_ -page and installed with following command: +Alternatively, *pygls* source code can be downloaded from our `GitHub`_ page and installed with following command: .. code:: console - python setup.py install + pip install git+https://github.com/openlawlibrary/pygls Quick Start ----------- @@ -78,13 +77,7 @@ Register Features and Commands def cmd_return_hello_world(ls, *args): return 'Hello World!' -See the `lsprotocol`_ module for the complete and canonical list of available features. - -Advanced usage --------------- - -To reveal the full potential of *pygls* (``thread management``, ``coroutines``, -``multi-root workspace``, ``TCP/STDIO communication``, etc.) keep reading. +See the :mod:`lsprotocol.types` module for the complete and canonical list of available features. Tutorial -------- @@ -92,6 +85,10 @@ Tutorial We recommend completing the :ref:`tutorial `, especially if you haven't worked with language servers before. +User Guide +---------- + +To reveal the full potential of *pygls* (``thread management``, ``coroutines``, +``multi-root workspace``, ``TCP/STDIO communication``, etc.) keep reading. .. _GitHub: https://github.com/openlawlibrary/pygls -.. _lsprotocol: https://github.com/microsoft/lsprotocol/blob/main/packages/python/lsprotocol/types.py diff --git a/docs/source/pages/testing.rst b/docs/source/pages/testing.rst index ba5ea251..99108354 100644 --- a/docs/source/pages/testing.rst +++ b/docs/source/pages/testing.rst @@ -11,8 +11,6 @@ have to mock the whole language server. If you skipped the advanced usage page, take a look at :ref:`passing language server instance ` section for more details. -Json Extension example's `unit tests`_ might be helpful, too. - Integration Tests ----------------- @@ -23,6 +21,4 @@ server, we used *pygls* to simulate the client and send desired requests to the server. To get a better understanding of how to set it up, take a look at our test `fixtures`_. - -.. _unit tests: https://github.com/openlawlibrary/pygls/blob/master/examples/json-vscode-extension/server/tests/unit -.. _fixtures: https://github.com/openlawlibrary/pygls/blob/master/tests/conftest.py#L29 +.. _fixtures: https://github.com/openlawlibrary/pygls/blob/main/tests/conftest.py diff --git a/docs/source/pages/tutorial.rst b/docs/source/pages/tutorial.rst index 44c68847..ae26af11 100644 --- a/docs/source/pages/tutorial.rst +++ b/docs/source/pages/tutorial.rst @@ -3,10 +3,16 @@ Tutorial ======== -In order to help you with using *pygls* in VSCode, we have created a simple `json-extension`_ example. +In order to help you with using *pygls* in VSCode, we have created the `vscode-playground`_ extension. .. note:: - You do not need this extension when using *pygls* with other text editors. + + This extension is meant to provide an environment in which you can easily experiment with a *pygls* powered language server. + It is not necessary in order to use *pygls* with other text editors. + + If you decide you want to publish your language server on the VSCode marketplace this + `template extension `__ + from Microsoft a useful starting point. Prerequisites ------------- @@ -82,18 +88,19 @@ Language server is **blocked**, because ``time.sleep`` is a **blocking** operation. This is why you didn't hit the breakpoint this time. .. hint:: - To make this command **non blocking**, add ``@json_server.thread()`` - decorator, like in code below: - .. code-block:: python + To make this command **non blocking**, add ``@json_server.thread()`` + decorator, like in code below: + + .. code-block:: python - @json_server.thread() - @json_server.command(JsonLanguageServer.CMD_COUNT_DOWN_BLOCKING) - def count_down_10_seconds_blocking(ls, *args): - # Omitted + @json_server.thread() + @json_server.command(JsonLanguageServer.CMD_COUNT_DOWN_BLOCKING) + def count_down_10_seconds_blocking(ls, *args): + # Omitted - *pygls* uses a **thread pool** to execute functions that are marked with - a ``thread`` decorator. + *pygls* uses a **thread pool** to execute functions that are marked with + a ``thread`` decorator. Non-Blocking Command Test @@ -194,7 +201,7 @@ Modify the Example We encourage you to continue to :ref:`advanced section ` and modify this example. -.. _json-extension: https://github.com/openlawlibrary/pygls/blob/master/examples/json-vscode-extension -.. _README: https://github.com/openlawlibrary/pygls/blob/master/examples/json-vscode-extension/README.md -.. _server.py: https://github.com/openlawlibrary/pygls/blob/master/examples/json-vscode-extension/server/server.py +.. _vscode-playground: https://github.com/openlawlibrary/pygls/blob/main/examples/vscode-playground +.. _README: https://github.com/openlawlibrary/pygls/blob/main/examples/vscode-playground/README.md +.. _server.py: https://github.com/openlawlibrary/pygls/blob/main/examples/servers/json_server.py .. _cooperative multitasking: https://en.wikipedia.org/wiki/Cooperative_multitasking