-
-
Notifications
You must be signed in to change notification settings - Fork 233
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: improve the template tutorial's readability #1154
Merged
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
f566231
improve the template tutorial's readability
lmgyuan 993c5ea
fix template context link
lmgyuan d9cc498
Revert "fix template context link"
lmgyuan 05cad9e
Merge branch 'master' into Edit_tutorial_Yuan
Florence-Njeri 82bd9c4
Apply suggestions from code review
lmgyuan e0d6340
Merge branch 'master' into Edit_tutorial_Yuan
Florence-Njeri a5edc79
Merge branch 'master' into Edit_tutorial_Yuan
Florence-Njeri File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -67,10 +67,22 @@ components: | |
|
||
1. Create a new directory for your template named **python-mqtt-client-template**. | ||
2. Install the AsyncAPI CLI using the command `npm install -g @asyncapi/cli`. | ||
3. Create a new folder **test/fixtures** with a file named **asyncapi.yml** in your fixtures directory. This file is used to define the **structure** of your template. | ||
4. Create a new file named **package.json** in your template directory. This file is used to define the **dependencies** for your template. | ||
5. Create a new file named **index.js** in your **template** directory. This file is used to define the **logic** for your template. | ||
6. Create a **test.py** file to validate the logic of your application. | ||
3. Create a new folder **test/fixtures** with a file named **asyncapi.yml** in your fixtures directory. This file is used to define the **structure** of your template. You can copy the above example and paste it in your **asyncapi.yml** document. | ||
4. Create a new file named **package.json** in your **python-mqtt-client-template** directory. This file is used to define the **dependencies** for your template. | ||
5. Create a new folder **python-mqtt-client-template/template**. Create a new file named **index.js** in your **template** directory. This file is used to define the **logic** for your template. | ||
6. Create a **test.py** file to validate the logic of your application. Don't worry about this file for now. The tutorial will tell you how to create it later. | ||
|
||
Now your directory should look like this: | ||
|
||
``` | ||
python-mqtt-client-template | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 👏🏼 |
||
├── template | ||
│ └── index.js | ||
├── test | ||
│ └── fixtures | ||
│ └── asyncapi.yml | ||
└── package.json | ||
``` | ||
|
||
Lets break it down: | ||
|
||
|
@@ -110,7 +122,7 @@ Here's what is contained in the code snippet above: | |
- **supportedProtocols** - A list that specifies which protocols are supported by your template. | ||
- **dependencies** - specifies which version of [`@asyncapi/generator-react-sdk`](https://github.com/asyncapi/generator-react-sdk) should be used. | ||
|
||
Run the command `npm install` on your terminal to install the dependencies specified in **package.json**. | ||
Navigate to the ****python-mqtt-client-template** directory. Run the command `npm install` on your terminal to install the dependencies specified in **package.json**. | ||
|
||
### index.js file | ||
|
||
|
@@ -143,7 +155,7 @@ The `asyncapi.info().title()` returns `Temperature Service`. | |
|
||
### Test using AsyncAPI CLI | ||
|
||
To see this in action, run `asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ -o test/project` command on your terminal. If successful, you'll see the message below on your terminal: | ||
To see this in action, navigate to the **python-mqtt-client-template** directory. Then, run `asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ -o test/project` command on your terminal. If successful, you'll see the message below on your terminal: | ||
|
||
``` cmd | ||
Generation in progress. Keep calm and wait a bit... done | ||
|
@@ -173,7 +185,7 @@ In this section, you'll: | |
|
||
### 1. Create the client | ||
|
||
The following is the sample code of the Python client you generated [above](#test-using-asyncapi-cli) using the Paho-MQTT library after running the `asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ -o test/project` command. | ||
Here is the sample code to be pasted in the client.py you generated above running the `asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ -o test/project` command. It uses the `paho-mqtt` package. | ||
|
||
``` python | ||
# 1 | ||
|
@@ -213,6 +225,20 @@ In summary, this code sets up an MQTT client using the Paho-MQTT library. It con | |
You'll interact with the Temperature Service using the client module you created above. You'll create an instance of the client using `client = TemperatureServiceClient()` and then use `client.sendTemperatureChange` function to publish messages that Temperature Service is subscribed to. | ||
Create a **test/project/test.py** file in your project and add the code snippet below: | ||
|
||
Now your directory should look like this: | ||
|
||
``` | ||
python-mqtt-client-template | ||
├── template | ||
│ └── index.js | ||
└── test | ||
├── fixtures | ||
│ └── asyncapi.yml | ||
└── project | ||
├── client.py | ||
└── test.py | ||
``` | ||
|
||
``` python | ||
from client import TemperatureServiceClient | ||
from random import randrange | ||
|
@@ -435,7 +461,7 @@ You'll then need to template to dynamically generate `sendTemperatureDrop` and ` | |
</Text> | ||
``` | ||
|
||
It's recommended to put reusable components outside template directory in a new directory called **components**. You'll create a component that will dynamically generate functions in the output for as many channels as there are in your AsyncAPI document that contain a `publish` operation. Add the following code in **components/TopicFunction.js** file: | ||
It's recommended to put reusable components outside the template directory in a new directory called components. You'll create a component that will dynamically generate functions in the output for as many channels as there are in your AsyncAPI document that contains a `publish` operation. Add the following code in the **python-mqtt-client-template/components/TopicFunction.js** file, after creating the **python-mqtt-client-template/components/** directory: | ||
|
||
```js | ||
/* | ||
|
@@ -512,6 +538,23 @@ export default function ({ asyncapi, params }) { | |
|
||
``` | ||
|
||
Now your directory should look like this: | ||
|
||
``` | ||
python-mqtt-client-template | ||
├── components | ||
│ └── TopicFunction.js | ||
├── template | ||
│ └── index.js | ||
└── test | ||
├── fixtures | ||
│ └── asyncapi.yml | ||
└── project | ||
├── client.py | ||
└── test.py | ||
``` | ||
|
||
|
||
Run `npm test` on your terminal to ensure everything works as expected. | ||
|
||
In the next section, you'll add another channel to **asyncapi.yml** file called `temperature/dropped` and `temperature/risen` then run the template again to make sure it still works as expected. | ||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yup, good 👁️