From c2f3b1c53d12c622b3f0e2dd718bae80fad5eb9a Mon Sep 17 00:00:00 2001 From: ViktarStarastsenka <99594890+ViktarStarastsenka@users.noreply.github.com> Date: Tue, 28 Mar 2023 19:11:47 +0100 Subject: [PATCH 1/4] Update README.md --- README.md | 292 +++++++++++------------------------------------------- 1 file changed, 58 insertions(+), 234 deletions(-) diff --git a/README.md b/README.md index ecbc60e..c4de1c8 100644 --- a/README.md +++ b/README.md @@ -1,124 +1,32 @@ ## Introduction -![Tutorials UI](docs/tutorials.png) - -The Tutorials are documents that contain helpful use cases, comments and interesting experience about Redis features and capabilities. - -The content of the Tutorials can be updated autonomously without a need to update the entire application. - -This document provides an overview of the Tutorials structure, its elements and contains instructions, recommendations, and best practices for updating the content of Tutorials. - +Tutorials are documents that contain helpful use cases, comments and interesting experience about Redis and Redis Stack capabilities. +It is a perfect tool to present your use cases and experience using RedisInsight Workbench and share them with others! +This page provides an overview of the Tutorials structure, its elements and contains instructions, recommendations, and best practices for updating and sharing Tutorials. ## Navigation -1. Examples -2. [Structure](#Structure) +1. [Structure](#Structure) +2. [Examples](#Examples) 3. [Pages](#Pages) -4. [Autoupdate Flow](#Autoupdate) -5. [Development Flow](#Development) - -## Examples -Download this example with Redis Stack Tutorials and upload the archive using the "Upload Tutorial" feature in Workbench so you can view and work with them in RedisInsight. - -[Redis Stack Tutorials.zip](https://github.com/RedisInsight/Tutorials/files/10911840/Redis.Stack.Tutorials.zip) +4. [Advanced button parameters](#Advanced) ## Structure -Tutorials allows you to render recursive objects, such as a file directory. - -On the root level of [sources](https://github.com/RedisInsight/Tutorials/tree/main/src) folder, we have `tutorials.json` and all necessary static files (markdowns, images, etc.) -The content of this area is generated based on Nodes specified inside `tutorials.json`. -This JSON file is described as a simple [Object](https://javascript.info/object) (Hash map), where key is a **string** and value is a **Node** (`Record`). Each Node requires a `label`,`type` and a unique `id` (all available properties are described in the table below). +Tutorials should be combined into a .zip archive that contains the following: +1. [Markdown files](#Markdown) with content of Tutorials +2. [manifest.json](#manifest.json) that describes the structure and befavior of Tutorials -| Prop | Type | Description | -| -------------------- | --------------------------------------- | ----------- | -| id (**required**) | string | | -| type (**required**) | "group", "internal-link", "code-button" | | -| label (**required**) | string | Label that will be displayed on UI for Node | -| children | Record | Use only for "group" type | -| args | Record | A special set of parameters required by a certain type of node (each type has its own) | - -A Node can be represented by various UI components and is specified by `type` prop. Supported types are listed below. - -| Type | Description | Args | -|----------------- |------------------------------------------------------------------------------------- |-------------- | -| **"internal-link"** | A link that opens a page inside the Tutorials
(e.g. link to Redis Stack tutorial). | - "path" (required, string) - relative file path | -| **"code-button"** | A button that inserts content into the Code Editor. | - "path" (required, string) - relative file path | -| **"group"** | Grouping several nodes into one directory/folder.
Allows you to create nested lists | - "initialIsOpen" (boolean) - The group will start in the open state (default value - false)
- "withBorder" (boolean) - Display border at the bottom (default value - false) | - -> _**!Note.** All **"internal-link"** nodes located in the same **"group"** will be connected to each other. And using pagination (created dynamically) you can go directly from one page to another. Therefore, it is best to combine elements into groups related to the same topic._ - -### Example with "Tutorials" group and two sections inside it -```json -{ - "tutorials": { - "type": "group", - "id": "tutorials", - "label": "TUTORIALS", - "args": { - "withBorder": true, - "initialIsOpen": true - }, - "children": { - "redis_stack": { - "type": "group", - "id": "redis_stack", - "label": "Redis Stack", - "args": { - "initialIsOpen": false - }, - "children": { - "working_with_json": { - "type": "internal-link", - "id": "working_with_json", - "label": "Working with JSON", - "args": { - "path": "/redis_stack/working_with_json.md" - } - }, - "vss": { - "type": "internal-link", - "id": "vector_similarity_search", - "label": "Vector Similarity Search", - "args": { - "path": "/redis_stack/vector_similarity_search.md" - } - } - } - } - } - } -} -``` -## Pages -By using **“internal-link”** node we can open other pages inside of Tutorials. To display more pages, add relevant files to the [src](https://github.com/RedisInsight/Tutorials/tree/main/src) folder. - -These tutorials may contain the following elements: -* Plain text -* [Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax/) -* [Extended Markdown Syntax](https://www.markdownguide.org/extended-syntax/) -* [HTML tags](https://www.markdownguide.org/basic-syntax/#html) -* Images -* Custom Syntax +## Examples +If you would like to start with Tutorials, download this example with Redis Stack Tutorials and upload the archive using the "Upload Tutorial" feature in RedisInsight Workbench so you can view and understand the overall logic. -### Images -Basic Markdown syntax provides the ability to render images. ([Image Markdown Syntax](https://www.markdownguide.org/basic-syntax/#images-1)) +[Redis Stack Tutorials.zip](https://github.com/RedisInsight/Tutorials/files/10911840/Redis.Stack.Tutorials.zip) -You can use the absolute path -``` -![RedisInsight Browser screenshot](https://github.com/RedisInsight/RedisInsight/blob/main/.github/redisinsight_browser.png) -``` -or relative path to image inside the [statics](https://github.com/RedisInsight/Tutorials) -``` -![RedisInsight Browser screenshot](/_images/browser.png) -``` +## Markdown files -#### Redis Code block -![Redis Code block](docs/tutorials-redis-code-block.png) +In short, Tutorials support the basic [Markdown syntax](https://www.markdownguide.org/basic-syntax/) that you can use to specify your information. +If you would like to add a button that will insert Redis commands to the Workbench Editor, use Redis Code block that is almost the same as for the [Fenced Code Block](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks), but you need to specify `redis` as language and the label next to it (see the `Create` button example below). -###### Manual-execute button -A button that inserts Redis commands in the Editor. The syntax is almost the same as for the [Fenced Code Block](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks), -the only difference is that you must specify `redis` as language and the label next to it (`Create` in the example below). ```` ```redis Create // Let's add three documents as Hashes. @@ -133,7 +41,49 @@ the only difference is that you must specify `redis` as language and the label n ``` ```` -###### Button parameters +## manifest.json + +Manifest.json is not required and can be skipped, in the case of missing manifest.json, RedisInsight will: +1. Take the Tutorial name from the .zip archive +2. All the pages will have names the same as file names in the .zip archive +3. The order of pages will be the same as in the .zip archive + +If you would like to customize or prettify the archive name, page names, or the order, you can use the manifest.json. This JSON file is described as simple [Objects](https://javascript.info/object) which represents tree node and might have children nodes inside. + +Manifest file should start with single Node and should have properties described +below (it will be displayed as type "group"): + +| Prop | Type | Description | +|-------------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| label (**required**) | string | Label that will be displayed on UI for Node | +| children (**required**) | Node[] | List of Nodes (nested groups or markdown files) | +| type | | Can be skipped - RedisInsight will always use the "group" parameter | +| author | string | Not required, Author name | +| URL | string | Not required, link to repository/web-site | +| industry | string[] | Not required, tags to show relevant industry | +| description | string | Not required, short description of tutorials | + +Each Node requires a `label`,`type` (all available properties are described in the table below). + +| Prop | Type | Description | +|----------------------|--------------------------|----------------------------------------------------------------------------------------| +| id | string | | +| type (**required**) | "group", "internal-link" | | +| label (**required**) | string | Label that will be displayed on UI for Node | +| children | Node[] | Use only for the "group" type | +| args | Record | A special set of parameters required by a certain type of node (each type has its own) | + +A Node can be represented by various UI components and is specified by `type` prop. Supported types are listed below. + +| Type | Description | Args | +|-----------------------|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------| +| **"internal-link"** | A link that opens a page inside the Enablement Area
(e.g. link to guide page). | - "path" (required, string) - relative file path | +| **"group"** | Grouping several nodes into one directory/folder.
Allows you to create nested lists | - "initialIsOpen" (boolean) - The group will start in the open state (default value - false) | + +> _**!Note.** All **"internal-link"** nodes located in the same **"group"** will be connected to each other. And using pagination (created dynamically) you can go directly from one page to another. Therefore, it is better to combine elements into groups related to the same topic._ + + +## Advanced button parameters You can customize the run parameters to configure the raw mode, pipeline parameter and group mode. If specified, they will override the configuration set in RedisInsight. If not specified - the behaviour will be defined by parameters set in RedisInsight. @@ -173,130 +123,4 @@ redis:[results=group;mode=ascii] redis:[auto=true;pipeline=8;mode=raw;results=single;] ``` -###### Auto-execute button -![img.png](docs/tutorials-redis-auto-code-block.png) - -A button that automatically executes the Redis commands (without inserting it into the Editor). Such buttons will be displayed with the "Play" icon inside. -The code syntax is the same as for the manually executed buttons, just insert parameter `[auto=true]` with any other parameters before the button. - -```` - ```redis:[auto=true;mode=raw] Create - // Let's add three documents as Hashes. - // Each document represents a building permit. - HSET permit:1 "description" "To reconstruct a single detached house with a front covered veranda." "construction_value" 42000 "building_type" "single detached house" "address_city" "Lisbon" "work_type" "demolition,reconstruction" "permit_timestamp" "1602156878" "address_street" "R. Da Palma" "location" "38.717746, -9.135839" - HSET permit:2 "description" "To construct a loft" "construction_value" 53000 "building_type" "apartment" "address_city" "Porto" "work_type" "construction" "permit_timestamp" "1556546400" "address_street" "Rua da Boavista" "location" "41.155854, -8.616721" - HSET permit:3 "description" "New house build" "construction_value" 260000 "building_type" "house" "address_city" "Lagos" "work_type" "construction;design" "permit_timestamp" "1612947600" "address_street" "R. Antonio Gedeao" "location" "37.114864, -8.668521" - ``` -```` - -## Autoupdate -Our application supports the ability to quickly update the static files of the Enablement area so that we can provide users with up-to-date information. - -EA tutorials auto-update flow: -1. Push commit with updates to the main branch -2. Wait until changes are merged into the latest branch -3. Reopen the Redisinsight with a working internet connection. In the background, new files will be downloaded to the user's local home directory: - * **Mac**: In the `/Users//.redisinsight-v2/tutorials` directory. - * **Windows**: In the `C:\Users\\.redisinsight-v2/tutorials` directory. - * **Linux**: In the `/home//.redisinsight-v2/tutorials` directory. -4. Open Enablement area on UI - -## Development -Let's imagine that we need to add a new group (Streams) with 2 pages (Basics, Getting data). - -Step by step implementation would be as follows: -1. First of all, it's best to create new pages locally and make sure that everything looks like it was planned. -2. Clone Tutorials repository (if you haven't done it before) and go into `/src` -3. Create a new branch from the `main` -4. Add new `streams` folder with `basics.md` and `getting-data.md`. As a result, the folder structure will look something like this. -``` -Tutorials - > Redis Stack - > Working with JSON - > streams - basics.md - getting-data.md - tutorials.json -``` -5. Add new nodes inside `tutorials.json` -```json -{ - "tutorials": { - "type": "group", - "id": "tutorials", - "label": "TUTORIALS", - "children": { - "redis_stack": {"id": "redis_stack"...}, - "streams": { - "type": "group", - "id": "streams", - "label": "Streams", - "children": { - "basics": { - "type": "internal-link", - "id": "basics", - "label": "Basics", - "args": { - "path": "/streams/basics.md" - } - }, - "get-data": { - "type": "internal-link", - "id": "getting-data", - "label": "Get Data", - "args": { - "path": "/streams/getting-data.md" - } - } - } - } - } - } -} - -``` -> _**!Note.** Markdown file name should have the same value as Node `id` to properly create pagination. _ -6. Fill markdowns with content. - -`basics.md` -```` -For the goal of understanding what Redis Streams are and how to use them, we will ignore all the advanced features, and instead focus on the data structure itself, in terms of commands used to manipulate and access it. -This is, basically, the part that is common to most of the other Redis data types, like Lists, Sets, Sorted Sets and so forth. -However, note that lists also have an optional more complex blocking API, exported by commands like BLPOP and similar. -So streams are not much different than lists in this regard, it's just that the additional API is more complex and more powerful. - -Because Streams are an append-only data structure, the fundamental write command, called **XADD**, appends a new entry into the specified stream. -A stream entry is not just a string but is instead composed of one or multiple field-value pairs. -This way, each entry of a stream is already structured, like an append-only file written in CSV format where multiple separated fields are present in each line. - -```redis Create -XADD mystream * sensor-id 1234 temperature 19.8 -``` - -```` - -`getting-data.md` -```` -Querying by range: **XRANGE** and **XREVRANGE* -To query the stream by the range we are only required to specify two IDs, _start_ and _end_. -The range returned will include the elements having start or end as ID, so the range is inclusive. The two special IDs - and + respectively mean the smallest and the greatest ID possible. - -```redis XRANGE -XRANGE mystream - + -``` - -```redis XREVRANGE -XREVRANGE mystream + - COUNT 1 -``` - - -```` -7. Open **RedisInsight** application with `TUTORIALS` environment variable `TUTORIALS_DEV_PATH='/src' ./` - - Example on Linux: `TUTORIALS='/home/user/projects/Tutorials/src' ./home/user/programms/RedisInsight.AppImage` -8. Make sure that everything looks fine. - - -9. After that, just commit and push, and then create Pull Request to the main branch. (Release flow described in the [Autoupdate Flow](#Autoupdate) section). - From b29bfcfeec336ed411ca7912fc7dc9705805cd59 Mon Sep 17 00:00:00 2001 From: ViktarStarastsenka <99594890+ViktarStarastsenka@users.noreply.github.com> Date: Tue, 28 Mar 2023 19:14:23 +0100 Subject: [PATCH 2/4] Update README.md --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c4de1c8..6f14426 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,8 @@ Tutorials should be combined into a .zip archive that contains the following: ## Examples If you would like to start with Tutorials, download this example with Redis Stack Tutorials and upload the archive using the "Upload Tutorial" feature in RedisInsight Workbench so you can view and understand the overall logic. -[Redis Stack Tutorials.zip](https://github.com/RedisInsight/Tutorials/files/10911840/Redis.Stack.Tutorials.zip) +[Redis-Tutorials.zip](https://github.com/RedisInsight/Tutorials/files/11092920/Redis-Tutorials.zip) + ## Markdown files From d731f1788f63b48d56a8947f2a96c7478b7d1aa6 Mon Sep 17 00:00:00 2001 From: ViktarStarastsenka <99594890+ViktarStarastsenka@users.noreply.github.com> Date: Wed, 29 Mar 2023 09:54:39 +0100 Subject: [PATCH 3/4] Update README.md --- README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 6f14426..5d365de 100644 --- a/README.md +++ b/README.md @@ -8,22 +8,20 @@ This page provides an overview of the Tutorials structure, its elements and cont 1. [Structure](#Structure) 2. [Examples](#Examples) -3. [Pages](#Pages) -4. [Advanced button parameters](#Advanced) +3. [Advanced button parameters](#Advanced) ## Structure Tutorials should be combined into a .zip archive that contains the following: -1. [Markdown files](#Markdown) with content of Tutorials -2. [manifest.json](#manifest.json) that describes the structure and befavior of Tutorials +1. [Markdown files](#Markdown) with the content of Tutorials +2. [Manifest.json](#Manifest) that describes the structure and behavior of Tutorials ## Examples If you would like to start with Tutorials, download this example with Redis Stack Tutorials and upload the archive using the "Upload Tutorial" feature in RedisInsight Workbench so you can view and understand the overall logic. [Redis-Tutorials.zip](https://github.com/RedisInsight/Tutorials/files/11092920/Redis-Tutorials.zip) - -## Markdown files +## Markdown In short, Tutorials support the basic [Markdown syntax](https://www.markdownguide.org/basic-syntax/) that you can use to specify your information. If you would like to add a button that will insert Redis commands to the Workbench Editor, use Redis Code block that is almost the same as for the [Fenced Code Block](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks), but you need to specify `redis` as language and the label next to it (see the `Create` button example below). @@ -42,7 +40,7 @@ If you would like to add a button that will insert Redis commands to the Workben ``` ```` -## manifest.json +## Manifest Manifest.json is not required and can be skipped, in the case of missing manifest.json, RedisInsight will: 1. Take the Tutorial name from the .zip archive @@ -84,7 +82,7 @@ A Node can be represented by various UI components and is specified by `type` pr > _**!Note.** All **"internal-link"** nodes located in the same **"group"** will be connected to each other. And using pagination (created dynamically) you can go directly from one page to another. Therefore, it is better to combine elements into groups related to the same topic._ -## Advanced button parameters +## Advanced You can customize the run parameters to configure the raw mode, pipeline parameter and group mode. If specified, they will override the configuration set in RedisInsight. If not specified - the behaviour will be defined by parameters set in RedisInsight. @@ -123,5 +121,3 @@ redis:[results=single;pipeline=4] redis:[results=group;mode=ascii] redis:[auto=true;pipeline=8;mode=raw;results=single;] ``` - - From 7e48d31bd33a76bfdf0872d6c324636e62c57fc7 Mon Sep 17 00:00:00 2001 From: ViktarStarastsenka <99594890+ViktarStarastsenka@users.noreply.github.com> Date: Wed, 29 Mar 2023 09:56:46 +0100 Subject: [PATCH 4/4] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5d365de..1aedebc 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ This page provides an overview of the Tutorials structure, its elements and cont Tutorials should be combined into a .zip archive that contains the following: 1. [Markdown files](#Markdown) with the content of Tutorials -2. [Manifest.json](#Manifest) that describes the structure and behavior of Tutorials +2. [manifest.json](#Manifest) that describes the structure and behavior of Tutorials ## Examples If you would like to start with Tutorials, download this example with Redis Stack Tutorials and upload the archive using the "Upload Tutorial" feature in RedisInsight Workbench so you can view and understand the overall logic.