From 4b53999a079082c84c0c236477eed729328a8e83 Mon Sep 17 00:00:00 2001
From: azerr <azerr@redhat.com>
Date: Sat, 2 Dec 2023 14:33:19 +0100
Subject: [PATCH] doc: Getting started documentation

Fixes #24

Signed-off-by: azerr <azerr@redhat.com>
---
 README.md                              |  3 ++
 docs/GettingStarted.md                 | 55 ++++++++++++++++++++++++++
 src/main/resources/META-INF/plugin.xml |  4 +-
 3 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 docs/GettingStarted.md

diff --git a/README.md b/README.md
index c7fd18bff..25230f37e 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,9 @@ LSP4IJ provides:
 * a `Language Servers settings page` to configure the LSP trace level, the debug port to use to debug language server:
 
 ![Language Server settings](https://github.com/redhat-developer/lsp4ij/blob/HEAD/docs/images/LanguageServerSettings.png?raw=true)
+
+You can start with [Getting started](./docs/GettingStarted.md)
+
 <!-- Plugin description end -->
 
 ## Who is using LSP4IJ?
diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md
new file mode 100644
index 000000000..9fc39e462
--- /dev/null
+++ b/docs/GettingStarted.md
@@ -0,0 +1,55 @@
+# Getting started
+
+This section explains step by step how to add your own LSP language server in your IntelliJ plugin.
+
+## Reference LSP4IJ
+
+### plugin.xml
+
+The first step is to reference LSP4IJ. LSP4IJ uses `com.redhat.devtools.lsp4ij` as plugin Id.
+
+You need [to declare dependency in your plugin.xml](https://plugins.jetbrains.com/docs/intellij/plugin-dependencies.html#3-dependency-declaration-in-pluginxml) like this:
+
+```xml
+<idea-plugin>
+  ...
+
+  <depends>com.redhat.devtools.lsp4ij</depends>
+
+  ...
+</idea-plugin>
+```
+
+### Exclude all LSP4J dependencies
+
+LSP4IJ depends on [Eclipse LSP4J](https://github.com/eclipse-lsp4j/lsp4j) (Java binding for the [Language Server Protocol](https://microsoft.github.io/language-server-protocol) and the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol).). It uses a given version of LSPJ and their classes are loaded in the LSP4IJ plugin class loader.
+
+Your IntelliJ Plugin should use `the same LSP4J classes than LSP4IJ` to avoid some `ClassCastException` errors. To do that you need to `exclude all LSP4J dependencies` from your plugin.
+
+Here a sample used in [Quarkus Tools](https://github.com/redhat-developer/intellij-quarkus) in [build.gradle.kts](https://github.com/redhat-developer/intellij-quarkus/blob/main/build.gradle.kts) to exclude LSP4J dependency from the [Qute Language Server](https://github.com/redhat-developer/quarkus-ls/tree/master/qute.ls) which have a dependency to LSP4J:
+
+```
+implementation("com.redhat.microprofile:com.redhat.qute.ls:0.17.0) {
+  exclude("org.eclipse.lsp4j")
+}
+```
+
+## Declare server
+
+TODO:
+
+ * create a LanguageServer + languageClient class
+ *  declare server in plugin.xml
+
+## Declare language mapping
+
+TODO 
+ * declare mapping
+ * DocumentMatcher
+
+## Declare IJ features
+
+ * externalAnnotator, completion, etc are declared an language any with LSP4IJ => nothing to do
+ * IJ inlayHint, hover doesn't support any language, so you need to declare them in you plugin.xml
+
+
diff --git a/src/main/resources/META-INF/plugin.xml b/src/main/resources/META-INF/plugin.xml
index a82acd686..d331b99ce 100644
--- a/src/main/resources/META-INF/plugin.xml
+++ b/src/main/resources/META-INF/plugin.xml
@@ -14,7 +14,7 @@
   </change-notes>
   <description>
     <![CDATA[
-    <p>LSP4IJ is a free and open-source <a href="https://microsoft.github.io/language-server-protocol/">Language Server protocol (LSP)</a> client compatible with all flavors of IntelliJ.</p>
+    <p><a href="https://github.com/redhat-developer/lsp4ij" >LSP4IJ</a> is a free and open-source <a href="https://microsoft.github.io/language-server-protocol/">Language Server protocol (LSP)</a> client compatible with all flavors of IntelliJ.</p>
 
     <p>It currently doesn't provide any useful functionality on its own but is instead used as a dependency for other extensions, willing to integrate language servers with IntelliJ products.</p>
 
@@ -29,6 +29,8 @@
         <li>An <code>LSP Consoles view</code> to track LSP requests, responses, and notifications in a console.</li>
         <li>A <code>Language Servers settings page</code> to configure the LSP trace level and the debug port to use to debug the language server.</li>
     </ul>
+    
+    <p>You can start with <a href="https://github.com/redhat-developer/lsp4ij/blob/main/docs/GettingStarted.md">Getting started</a></p>
     ]]>
   </description>