Provide embedded documentation

Fixes jlandersen#35 Signed-off-by: azerr <[email protected]>
angelozerr · Jan 27, 2021 · 1809450 · 1809450
1 parent 077bdbb
commit 1809450
Show file tree

Hide file tree

Showing 17 changed files with 1,089 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -20,14 +20,25 @@ Planned features in no particular order:
 - More administration features
 - Update configs
 
-## Screenshots
-![Screenshot-1](assets/screen-1.png)
+You might also find useful information in the [Online Documentation](https://github.com/jlandersen/vscode-kafka/blob/master/docs/README.md)
+or you can read this documentation inside your editor with the command `Open Documentation` available with `Ctrl+Shift+P`:
 
-![Screenshot-2](assets/screen-2.png)
+![Open Documentation](docs/assets/open-doc-cmd.png)
 
-![Screenshot-3](assets/screen-3.png)
+## Kafka explorer
+
+The Kafka explorer shows configured clusters with their topics, brokers, consumers and configurations.
+
+![Screenshot-1](docs/assets/screen-1.png)
+
+![Screenshot-2](docs/assets/screen-2.png)
+
+![Screenshot-3](docs/assets/screen-3.png)
+
+See [Kafka explorer](https://github.com/jlandersen/vscode-kafka/blob/master/docs/Explorer.md) section for more informations.
+
+## Producing messages
 
-## Producing
 Producing can be done by creating a `.kafka` file. Write simple producers using the following format:
 
 ```json
@@ -45,22 +56,15 @@ topic: json-events
 }
 ```
 
-For actually producing a single record, click on the "Produce record" link above the PRODUCER line; for producing 10 records, click on "Produce record x 10".
-The log about produced messages is printed in the "Kafka Producer Log" Output view.
-
-Record content can be randomized by injecting mustache-like placeholders of [faker.js properties](https://github.com/Marak/faker.js#api-methods), like ``{{name.lastName}}`` or ``{{random.number}}``. Some randomized properties can be localized via the `kafka.producers.fakerjs.locale` setting.
-
-![Screenshot-4](assets/screen-4.png)
+![Screenshot-4](docs/assets/screen-4.png)
 
-## Consuming
-Consuming topics can be done by right clicking a topic in the explorer or from the command palette.  Some things to note about consuming:
+See [Producing messages](https://github.com/jlandersen/vscode-kafka/blob/master/docs/Producing.md) section for more informations.
 
-* UTF-8 encoded keys and values only. If data is encoded differently, it will not be pretty.
-* One consumer group is created per topic (may change in the future to just have one for the extension).
+## Consuming messages
 
-Consumers are based on virtual documents, available in the VS Code extension API. A consumer will keep running even if you close the document in the editor. You should make sure to close the consumer explicitly, either via the command palette, the status bar element or the start/stop action button as well. The VS Code API does not support detecting if a virtual document is closed immediately. Instead, the underlying virtual document is automatically closed after two minutes if the document is closed in the editor.
+Consuming topics can be done by right clicking a topic in the explorer or from the command palette.  
 
-You can configure start offset for new consumers in settings (earliest, latest).
+See [Consuming messages](https://github.com/jlandersen/vscode-kafka/blob/master/docs/Consuming.md) section for more informations.
 
 ## CI Builds
 
@@ -69,4 +73,4 @@ vscode-kafka is built using Github Actions. Here's how to download and install t
 - Click on the most recent run,
 - Locate the vscode-kafka artifact down the page and download it,
 - Unzip the archive,
-- Install the vscode-kafka-*.vsix extension by following these [instructions](https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix).
+- Install the vscode-kafka-*.vsix extension by following these [instructions](https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix).
diff --git a/docs/Consuming.md b/docs/Consuming.md
@@ -0,0 +1,14 @@
+# Consuming messages
+
+Consuming topics can be done by right clicking a topic in the explorer or from the command palette.  Some things to note about consuming:
+
+* UTF-8 encoded keys and values only. If data is encoded differently, it will not be pretty.
+* One consumer group is created per topic (may change in the future to just have one for the extension).
+
+Consumers are based on virtual documents, available in the VS Code extension API. A consumer will keep running even if you close the document in the editor. You should make sure to close the consumer explicitly, either via the command palette, the status bar element or the start/stop action button as well. The VS Code API does not support detecting if a virtual document is closed immediately. Instead, the underlying virtual document is automatically closed after two minutes if the document is closed in the editor.
+
+## Preferences
+
+### `kafka.consumers.offset`
+
+You can configure start offset for new consumers in settings (earliest, latest).
diff --git a/docs/Explorer.md b/docs/Explorer.md
@@ -0,0 +1,23 @@
+# Explorer
+
+The Kafka explorer shows configured clusters with their topics, brokers, consumers and configurations.
+
+![Screenshot-1](assets/screen-1.png)
+
+![Screenshot-2](assets/screen-2.png)
+
+![Screenshot-3](assets/screen-3.png)
+
+## Preferences
+
+### `kafka.explorer.topics.sort`
+
+Choose sorting for topics in explorer.
+
+### `kafka.explorer.topics.filter`
+
+Glob patterns filtering topics out of the Kafka explorer. `*` matches any string, `?` matches a single character.
+
+### `kafka.explorer.consumers.filter`
+
+Glob patterns filtering consumer groups out of the Kafka explorer. `*` matches any string, `?` matches a single character.
diff --git a/docs/Producing.md b/docs/Producing.md
@@ -0,0 +1,35 @@
+# Producing messages
+
+Producing can be done by creating a `.kafka` file. Write simple producers using the following format:
+
+```
+PRODUCER keyed-message
+topic: my-topic
+key: mykeyq
+record content
+
+###
+
+PRODUCER non-keyed-json-message
+topic: json-events
+{
+    "type": "my_test_event"
+}
+```
+
+For actually producing a single record, click on the `Produce record` link above the `PRODUCER` line; for producing 10 records, click on `Produce record x 10`.
+The log about produced messages is printed in the `Kafka Producer Log` Output view.
+
+## Randomized content
+
+Record content can be randomized by injecting mustache-like placeholders of [faker.js properties](https://github.com/Marak/faker.js#api-methods), like ``{{name.lastName}}`` or ``{{random.number}}``. Some randomized properties can be localized via the `kafka.producers.fakerjs.locale` setting.
+
+![Screenshot-4](assets/screen-4.png)
+
+### `kafka.producers.fakerjs.enabled`
+
+Enable injection of [faker.js](https://github.com/marak/Faker.js/#api-methods)-randomized data in record templates, using the mustache syntax.
+
+### `kafka.producers.fakerjs.locale`
+
+[experimental] The locale used to generate [faker.js](https://github.com/marak/Faker.js/#api-methods)-randomized data in record templates.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,7 @@
+# Kafka Documentation
+
+Welcome to the [vscode-kafka](https://github.com/jlandersen/vscode-kafka) documentation.
+
+* [Kafka Explorer](Explorer.md#explorer)
+* [Producing messages](Producing.md#producing-messages)
+* [Consuming messages](Consuming.md#consuming-messages)
diff --git a/docs/assets/open-doc-cmd.png b/docs/assets/open-doc-cmd.png
diff --git a/assets/screen-1.png → docs/assets/screen-1.png b/assets/screen-1.png → docs/assets/screen-1.png
diff --git a/assets/screen-2.png → docs/assets/screen-2.png b/assets/screen-2.png → docs/assets/screen-2.png
diff --git a/assets/screen-3.png → docs/assets/screen-3.png b/assets/screen-3.png → docs/assets/screen-3.png
diff --git a/assets/screen-4.png → docs/assets/screen-4.png b/assets/screen-4.png → docs/assets/screen-4.png