Adding upstream version 1.3.0.upstream/1.3.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 94 insertions, 0 deletions

diff --git a/docs/source/pages/getting_started.rst b/docs/source/pages/getting_started.rst
new file mode 100644
index 0000000..e73d20f
--- /dev/null
+++ b/docs/source/pages/getting_started.rst
@@ -0,0 +1,94 @@
+Getting Started
+===============
+
+This document explains how to install *pygls* and get started writing language
+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:
+
+   - `Language Server Protocol Overview <https://microsoft.github.io/language-server-protocol/overview>`_
+   - `Language Server Protocol Specification <https://microsoft.github.io/language-server-protocol/specification>`_
+   - `Language Server Protocol SDKs <https://microsoft.github.io/language-server-protocol/implementors/sdks/>`_
+
+
+Installation
+------------
+
+To get the latest release from *PyPI*, simply run:
+
+.. code:: console
+
+   pip install pygls
+
+Alternatively, *pygls* source code can be downloaded from our `GitHub`_ page and installed with following command:
+
+.. code:: console
+
+   pip install git+https://github.com/openlawlibrary/pygls
+
+Quick Start
+-----------
+
+Spin the Server Up
+~~~~~~~~~~~~~~~~~~
+
+*pygls* is a language server that can be started without writing any additional
+code:
+
+.. code:: python
+
+   from pygls.server import LanguageServer
+
+   server = LanguageServer('example-server', 'v0.1')
+
+   server.start_tcp('127.0.0.1', 8080)
+
+After running the code above, server will start listening for incoming
+``Json RPC`` requests on ``http://127.0.0.1:8080``.
+
+Register Features and Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*pygls* comes with an API for registering additional features like
+``code completion``, ``find all references``, ``go to definition``, etc.
+
+.. code:: python
+
+    @server.feature(TEXT_DOCUMENT_COMPLETION, CompletionOptions(trigger_characters=[',']))
+    def completions(params: CompletionParams):
+        """Returns completion items."""
+        return CompletionList(
+            is_incomplete=False,
+            items=[
+                CompletionItem(label='Item1'),
+                CompletionItem(label='Item2'),
+                CompletionItem(label='Item3'),
+            ]
+        )
+
+… as well as custom commands:
+
+.. code:: python
+
+   @server.command('myVerySpecialCommandName')
+   def cmd_return_hello_world(ls, *args):
+       return 'Hello World!'
+
+See the :mod:`lsprotocol.types` module for the complete and canonical list of available features.
+
+Tutorial
+--------
+
+We recommend completing the :ref:`tutorial <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