Skip to content

Commit

Permalink
[doc] fix broken link in codegen guide (#28348)
Browse files Browse the repository at this point in the history
It appears that link to file on same GitHub path doesn't work and we need a full URL.
  • Loading branch information
jeremymeng authored Jan 24, 2024
1 parent e336560 commit 5d008b0
Showing 1 changed file with 18 additions and 18 deletions.
36 changes: 18 additions & 18 deletions documentation/steps-after-generations.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ rush build -t <your-package-name>
# Improve README.md document

A minimal README.md is generated by TypeScript emitter and you could improve README.md file per your service. To learn more about README, see below example README file.
- RLC example: [Maps Route README.md](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/maps/maps-route-rest/README.md)
- RLC example: [Maps Route README.md](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/maps/maps-route-rest/README.md)
- DPG example: [OpenAI README.md](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/openai/openai/README.md)

# How to write test for DPG/RLC
Expand All @@ -25,14 +25,14 @@ In order to release it, we need to add some tests for it to make sure we are del
See the [Javascript Codegen Quick Start for Test](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/Quickstart-on-how-to-write-tests.md) for information on how to write and run tests for the Javascript SDK.

1. **Write the test**
You could follow the [basic RLC test interaction and recording example](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/Quickstart-on-how-to-write-tests.md#example-1-basic-rlc-test-interaction-and-recording-for-azure-data-plane-service) to write your test step by step.

You could follow the [basic RLC test interaction and recording example](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/Quickstart-on-how-to-write-tests.md#example-1-basic-rlc-test-interaction-and-recording-for-azure-data-plane-service) to write your test step by step.

Also you could refer below examples for more cases:
- RLC example: [OpenAI Testing](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/openai/openai/test/public)
- DPG example: [Maps Route Testing](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/maps/maps-route-rest/test/public)

2. **Run the test**
2. **Run the test**
Now, you can run the test like this. If you are the first time to run test, you need to set the environment variable `TEST_MODE` to `record`. This will generate recordings for your test they could be used in `playback` mode.
On Linux, you could use `export` to set env variable:
```shell
Expand All @@ -58,24 +58,24 @@ See the [Javascript Codegen Quick Start for Test](https://github.com/Azure/azure

# How to write samples

We highly encourage you to write some valid samples for your customer to get start your service with libraries. You may author TypeScript samples under the `samples-dev` folder. For quick start you can use [sample-dev template](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/template/template/samples-dev) as reference and update the relevant information for your service such as package-name, sample code, description, etc.
We highly encourage you to write some valid samples for your customer to get start your service with libraries. You may author TypeScript samples under the `samples-dev` folder. For quick start you can use [sample-dev template](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/template/template/samples-dev) as reference and update the relevant information for your service such as package-name, sample code, description, etc.

To learn more you could refer below samples:
- DPG sample: [the samples of OpenAIClient](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/openai/openai/samples-dev)
- RLC sample: [the samples of MapsRouteClient](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/maps/maps-route-rest/samples-dev)

After the samples-dev folder change is finished, you will need to change the tsconfig.json to make sure the dev samples can be compiled and build correctly.
After the samples-dev folder change is finished, you will need to change the tsconfig.json to make sure the dev samples can be compiled and build correctly.

You will need to add this part to the "compilerOptions" of your tsconfig.json file so that the Samples engine could resolve the sample-dev package against the source code of the SDK.
You will need to add this part to the "compilerOptions" of your tsconfig.json file so that the Samples engine could resolve the sample-dev package against the source code of the SDK.
``` json
"paths": { "@azure/agrifood-farming": ["./src/index"] }
"paths": { "@azure/agrifood-farming": ["./src/index"] }
```
And change the *"include"* part into
And change the *"include"* part into
```json
"include": ["./src/**/*.ts", "./test/**/*.ts", "samples-dev/**/*.ts"],
```
Then, we provide tools to automatically change it into workable samples in both TypeScript and JavaScript. and you just need to add a sampleConfiguration in your package.json.
Then, we provide tools to automatically change it into workable samples in both TypeScript and JavaScript. and you just need to add a sampleConfiguration in your package.json.
You will need to add a sample configuration section in your package.json file and put the following content into it.
```json
Expand All @@ -91,16 +91,16 @@ Now, you can generate both JavaScript and TypeScript workable samples with the f
```shell
npm install -g common/tools/dev-tool # make sure you are in the azure-sdk-for-js repo root directory
cd ${PROJECT_ROOT}
npx dev-tool samples publish -f
npx dev-tool samples publish -f
```
You will see the workable samples in the `${PROJECT_ROOT}/samples` folder.
You will see the workable samples in the `${PROJECT_ROOT}/samples` folder.
# Format both the generated code and manual code
After you have finished the generation and added your own tests or samples, You can use the following command to format the code.
After you have finished the generation and added your own tests or samples, You can use the following command to format the code.
```shell
cd ${PROJECT_ROOT} && rushx format
```
Also we'll recommand you to run `lint` command to analyze your code and quickly find any problems.
```shell
Expand Down Expand Up @@ -164,9 +164,9 @@ extends:
safeName: azureagrifoodfarming # azureagrifoodfarming for DPG; azurerestagrifoodfarming for RLC
```
Please change the paths.include value as your own project path, and change the Artifacts name and safeName into yours.
Please change the paths.include value as your own project path, and change the Artifacts name and safeName into yours.
If there's already a ci.yml file in your project path. then the only thing you need to do is to add the Artifacts name and safeName of yours into that ci.yml.
If there's already a ci.yml file in your project path. then the only thing you need to do is to add the Artifacts name and safeName of yours into that ci.yml.
Please notice the Artifacts name should align with your package name. Here the package name is `@azure/agrifood-farming` so the relevant Artifacts name is `azure-agrifood-farming`.
Expand All @@ -185,7 +185,7 @@ You shall update the version number according to [semantic versioning rule](http
## Test recordings
After [writing and running test cases](#how-to-write-test-for-dpgrlc), you need to push the recordings to [assets repo](https://github.com/Azure/azure-sdk-assets). Please refer to [push recording guide](Quickstart-on-how-to-write-tests.md#how-to-push-test-recordings-to-assets-repo) to push recordings.
After [writing and running test cases](#how-to-write-test-for-dpgrlc), you need to push the recordings to [assets repo](https://github.com/Azure/azure-sdk-assets). Please refer to [push recording guide](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/Quickstart-on-how-to-write-tests.md#how-to-push-test-recordings-to-assets-repo) to push recordings.
## Fix CI for PR
You may meet the CI failures after submitting the PR, so please refer to [Troubleshoot CI Failure](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/Troubleshoot-ci-failure.md) to fix it.
Expand Down

0 comments on commit 5d008b0

Please sign in to comment.