From 9c2d179cea1d57479058b8aac92133d7d437cf78 Mon Sep 17 00:00:00 2001 From: azerr Date: Tue, 13 Oct 2020 16:18:35 +0200 Subject: [PATCH] Avoid duplication of documentation between extension and wiki Fixes #331 Signed-off-by: azerr --- docs/Extensions.md | 8 +++++++- docs/Preferences.md | 10 ++++++---- docs/README.md | 16 ++++++++++++++++ docs/Troubleshooting.md | 23 +++++++++++++++++++++++ package.json | 10 +++++++++- src/commands.ts | 2 ++ src/extension.ts | 15 ++++++++++++--- 7 files changed, 75 insertions(+), 9 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/Troubleshooting.md diff --git a/docs/Extensions.md b/docs/Extensions.md index b429d9b0..bb7fb59e 100644 --- a/docs/Extensions.md +++ b/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) \ No newline at end of file diff --git a/docs/Preferences.md b/docs/Preferences.md index fc699d7a..2176182c 100644 --- a/docs/Preferences.md +++ b/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). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..5954ce5c --- /dev/null +++ b/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)? \ No newline at end of file diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md new file mode 100644 index 00000000..66df7265 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/package.json b/package.json index 0da3f58f..2e6c96be 100644 --- a/package.json +++ b/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", diff --git a/src/commands.ts b/src/commands.ts index 1ef03ea0..2202cf4b 100644 --- a/src/commands.ts +++ b/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"; } \ No newline at end of file diff --git a/src/extension.ts b/src/extension.ts index 8bdef9d1..b83b32aa 100644 --- a/src/extension.ts +++ b/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": [],