Avoid duplication of documentation between extension and wiki

Fixes redhat-developer#331

Signed-off-by: azerr <[email protected]>

docs/Extensions.md

@@ -1,4 +1,6 @@
-# Custom XML Extensions
+# Extensions
+
+## Custom XML Extensions
 
 The [LemMinX - XML Language Server](https://github.com/eclipse/lemminx) can be extended to support custom completion, hover, validation, rename, etc by using the [Java Service Provider Interface (SPI)](https://www.baeldung.com/java-spi) mechanism.
 vscode-xml provides the ability to use your custom XML support provider, by adding external jars to the XML language server's classpath.
@@ -34,3 +36,7 @@ To do that:
 You can see the [vscode-xml-maven](https://github.com/angelozerr/vscode-xml-maven) sample which registers custom maven completion [MavenCompletionParticipant](https://github.com/eclipse/lemminx-maven/blob/master/lemminx-maven/src/main/java/org/eclipse/lemminx/extensions/maven/MavenCompletionParticipant.java#L210) for scope:
 
 ![demo of vscode xml maven suggesting different scopes for a dependency](./images/vscode-xml-maven.gif)
+
+## XML extension API (TypeScript)
+
+See [PR 292](https://github.com/redhat-developer/vscode-xml/pull/292)

docs/Preferences.md

@@ -1,3 +1,5 @@
+# Preferences
+
 ## Java Home
 
   vscode-xml requires Java JDK (or JRE) 8 or more recent in order to run.
@@ -63,7 +65,7 @@
   ]
   ```
 
-  Please see [XSD file associations](Validation#xml-file-association-with-xsd) and [DTD file associations](Validation#xml-file-association-with-dtd) for more information.
+  Please see [XSD file associations](Validation.md#xml-file-association-with-xsd) and [DTD file associations](Validation.md#xml-file-association-with-dtd) for more information.
 
 ## Catalogs
 
@@ -96,11 +98,11 @@
 
 ## Formatting
 
-See the [Formatting page](Formatting#formatting).
+See the [Formatting page](Formatting.md#formatting).
 
 ## Code Lens
 
-Use `xml.codeLens.enabled` in order to enable or disable code lens. Please see [the Code Lens page](CodeLens#code-lens) for more information.
+Use `xml.codeLens.enabled` in order to enable or disable code lens. Please see [the Code Lens page](CodeLens.md#code-lens) for more information.
 
 ## Documentation Type
 
@@ -173,4 +175,4 @@ JARs can be contributed to the LemMinX classpath using the `xml.extension.jars`
 These paths can include globs.
 This feature is only intended to be used for LemMinX extension development purposes.
 Distributing vscode-xml extensions is best done through the mechanism described in the
-[vscode-xml extension development documentation](Extensions#custom-xml-extensions).
+[vscode-xml extension development documentation](Extensions.md#custom-xml-extensions).

docs/README.md

@@ -0,0 +1,16 @@
+# XML Documentation
+
+Welcome to the [vscode-xml](https://github.com/redhat-developer/vscode-xml) documentation.
+
+## User Guide
+
+As [vscode-xml](https://github.com/redhat-developer/vscode-xml) consumes the [LemMinX XML Language Server](https://github.com/eclipse/lemminx) written in `Java`, it requires `Java`. Please start reading [here](Preferences.md#java-home).
+
+  * [XML Validation](Validation.md#xml-validation): How to validate XML with a grammar (XSD/DTD)?
+  * [Preferences](Preferences.md#preferences): More info on available [vscode-xml](https://github.com/redhat-developer/vscode-xml) preferences.
+  * [Formatting](Formatting.md#formatting): More info on the available formatting preferences.
+  * [Troubleshooting](Troubleshooting.md#troubleshooting): Info on troubleshooting and fixes to issues.
+
+## Developer Guide
+
+  * [Extensions](Extensions.md#extensions): How to extend vscode-xml settings and XML features (completion, validation, hover, etc)?

docs/Troubleshooting.md

@@ -0,0 +1,23 @@
+# Troubleshooting
+
+## Issues 
+
+Please create [vscode-xml issues](https://github.com/redhat-developer/vscode-xml/issues) for any problem.
+
+### No support on xml file.
+
+Sometimes an old instance of the XML Language Server is still running.
+
+You can check if the server is not working in VSCode by going to:
+ 1) Turning on `xml.trace.server` in the VSCode preferences
+ 2) `View -> Output -> XML Support` (drop down menu top right)
+    If it is not working it will indicate the server has Shutdown.
+
+You can kill the process by: 
+
+ 1) Run `jps` command in terminal
+ 2) Check if multiple instances of `org.eclipse.lemminx-uber.jar` or `XMLServerLauncher`
+ 3) According to your OS:
+
+  * on Windows OS: run `taskkill /F /PID ...` all instances
+  * on other OS: run `kill -9 ...` all instances

package.json

@@ -24,7 +24,8 @@
   "activationEvents": [
     "onLanguage:xml",
     "onLanguage:xsl",
-    "onCommand:xml.open.docs"
+    "onCommand:xml.open.docs",
+    "onCommand:xml.open.docs.home"
   ],
   "main": "./dist/extension",
   "scripts": {
@@ -373,6 +374,13 @@
         "files.trimTrailingWhitespace": false
       }
     },
+    "commands": [
+      {
+        "command": "xml.open.docs.home",
+        "title": "Open XML Documentation",
+        "category": "XML"
+      }
+    ],
     "languages": [
       {
         "id": "xml",

src/commands.ts

@@ -48,4 +48,6 @@ export namespace Commands {
     export const MARKDOWN_API_RENDER = 'markdown.api.render';
 
     export const OPEN_DOCS = "xml.open.docs";
+
+    export const OPEN_DOCS_HOME = "xml.open.docs.home";
 }

src/extension.ts

@@ -136,13 +136,22 @@ namespace ActionableNotification {
 let languageClient: LanguageClient;
 
 export function activate(context: ExtensionContext) {
+  // Register commands for XML documentation
   context.subscriptions.push(markdownPreviewProvider);
-  context.subscriptions.push(commands.registerCommand(Commands.OPEN_DOCS, async (params) => {
-    const uri = params.page + '.md';
+  context.subscriptions.push(commands.registerCommand(Commands.OPEN_DOCS_HOME, async () => {
+    const uri = 'README.md';
+    const title = 'XML Documentation';
+    const sectionId = '';
+    markdownPreviewProvider.show(context.asAbsolutePath(path.join('docs', uri)), title, sectionId, context);
+  }));
+  context.subscriptions.push(commands.registerCommand(Commands.OPEN_DOCS, async (params: {page: string, section: string}) => {
+    const page = params.page.endsWith('.md') ? params.page.substr(0, params.page.length - 3) : params.page;
+    const uri = page  + '.md';
     const sectionId = params.section || '';
-    const title = 'XML ' + params.page;
+    const title = 'XML ' + page;
     markdownPreviewProvider.show(context.asAbsolutePath(path.join('docs', uri)), title, sectionId, context);
   }));
+
   let storagePath = context.storagePath;
   const externalXmlSettings = {
     "xmlCatalogs": [],