Skip to content

Commit 8a3dbe9

Browse files
qiaozhaqiaozha
authored
add-cli-readme-files-template (#12137)
1 parent 3a3a945 commit 8a3dbe9

File tree

5 files changed

+295
-2
lines changed

5 files changed

+295
-2
lines changed

‎documentation/code-gen/configure-cli.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# Readme Configuration Guide for Azure CLI
2+
This file describe how to configure readme files to make it available for Azure CLI code generation.
3+
4+
## Common Configuration
5+
In order to use cli codegen. We need readme.az.md and readme.cli.md and readme.python.md to be ready.
6+
where the readme.cli.md is the common configuration for all the command line tools like Azure CLI, Powershell, Terraform etc. not only for Azure CLI.
7+
and the readme.az.md is specific configuration for Azure CLI.
8+
Because Azure CLI is calling Azure SDK for Python in the implementation layer. we need readme.python.md to be ready, we can refer to [configure-python-sdk.md](./configure-python-sdk.md) for more details about it.
9+
10+
11+
### Basic Information
12+
Configure package title/description/tag.
13+
~~~~
14+
// file: readme.md
15+
16+
``` yaml
17+
title: xxxxConfigurationClient
18+
description: xxxx Configuration Client
19+
openapi-type: arm
20+
tag: package-xxxx-xx-xx
21+
```
22+
~~~~
23+
24+
### tag
25+
Tags are used to define what swagger files are used in specific client SDK. In Single-API client, only one tag can be used to generate SDK client.
26+
A tag can contains a bunch of swagger files which are used to generate the SDK.
27+
28+
The name of a tag should be in form of package-yyyy-mm-dd[-xxx], for example below tag names are available:
29+
- package-2020-02-03
30+
- package-2020-03-22-preview
31+
- package-2020-05-03-only
32+
33+
while the below tag names are invalid names:
34+
- 2020-03-04
35+
- package-preview-2020-03-04
36+
37+
A tag can be configured like below:
38+
~~~~
39+
// file: readme.md
40+
41+
42+
### Tag: package-2019-12-01
43+
44+
These settings apply only when `--tag=package-2019-12-01` is specified on the command line.
45+
46+
``` yaml $(tag) == 'package-2019-12-01'
47+
input-file:
48+
- Microsoft.Compute/stable/2019-12-01/compute.json
49+
- Microsoft.Compute/stable/2019-12-01/runCommands.json
50+
- Microsoft.Compute/stable/2019-12-01/gallery.json
51+
```
52+
~~~~
53+
54+
55+
## Swagger to SDK
56+
To make Azure SDK for Javascript (Typescript) can be generated from the tag, swagger-to-sdk need to be configured:
57+
58+
~~~
59+
// file: readme.md
60+
61+
## Swagger to SDK
62+
63+
This section describes what SDK should be generated by the automatic system.
64+
This is not used by Autorest itself.
65+
66+
``` yaml $(swagger-to-sdk)
67+
swagger-to-sdk:
68+
- repo: azure-cli-extensions
69+
- ...
70+
71+
72+
## AZ
73+
74+
See configuration in [readme.az.md](./readme.az.md)
75+
~~~
76+
77+
## Az Configuration
78+
Az dedicated configurations are configured in readme.az.md.
79+
the typical package-name is usually like `@azure/arm-xxx` where the xxx is related with the service name.
80+
and the typical output-folder in the azure-sdk-for-js is like `$(typescript-sdks-folder)/sdk/xxx/arm-xxx` where the xxx is related with the service name.
81+
A typical readme.az.md is like this:
82+
~~~
83+
// file: readme.az.md
84+
85+
## AZ
86+
87+
These settings apply only when `--az` is specified on the command line.
88+
89+
``` yaml $(az) && $(target-mode) != 'core'
90+
az:
91+
extensions: communication
92+
namespace: azure.mgmt.communication
93+
package-name: azure-mgmt-communication
94+
az-output-folder: $(azure-cli-extension-folder)/src/communication
95+
python-sdk-output-folder: "$(az-output-folder)/azext_communication/vendored_sdks/communication"
96+
# add additinal configuration here specific for Azure CLI
97+
# refer to the faq.md for more details
98+
```
99+
100+
~~~
101+
102+
## Multi-api
103+
Currently the Azure CLI code generator doesn't support multi-api which means each operation contained in one package should only contains one api-version's.
104+
105+
## Multi-packages
106+
The batch is a tag list which are used in the one RP has multi-package scenarios. For example,
107+
the Migrate RP has two independent packages like migrate and offazure.
108+
First of all, you need to have different yaml block for each package to define the default tag for that specific package.
109+
~~~
110+
// file: readme.md
111+
## Configuration
112+
113+
### Basic Information
114+
115+
These are the global settings for the Resource API.
116+
117+
``` yaml
118+
openapi-type: arm
119+
```
120+
121+
``` yaml $(package-migrate)
122+
tag: package-migrate-2019-10
123+
```
124+
125+
``` yaml $(package-offazure)
126+
tag: package-offazure-2020-01
127+
```
128+
129+
~~~
130+
Then for each default tag, you can define the input swagger like normal tag.
131+
~~~
132+
133+
### Tag: package-migrate-2019-10
134+
135+
These settings apply only when `--tag=package-migrate-2019-10` is specified on the command line.
136+
137+
``` yaml $(tag) == 'package-migrate-2019-10'
138+
input-file:
139+
- Microsoft.Migrate/stable/2019-10-01/migrate.json
140+
```
141+
142+
### Tag: package-offazure-2020-01
143+
144+
These settings apply only when `--tag=package-offazure-2020-01` is specified on the command line.
145+
146+
``` yaml $(tag) == 'package-offazure-2020-01'
147+
input-file:
148+
- Microsoft.OffAzure/stable/2020-01-01/migrate.json
149+
```
150+
151+
~~~
152+
153+
Thirdly, in your readme.az.md you should include what packages you want to include in the Azure CLI.
154+
And in each package's section define the default package name output folder in azure-cli-extensions repo etc.
155+
156+
~~~
157+
## AZ
158+
159+
These settings apply only when `--az` is specified on the command line.
160+
``` yaml $(az)
161+
batch:
162+
- package-migrate: true
163+
- package-offazure: true
164+
```
165+
166+
``` yaml $(az) && $(package-migrate)
167+
az:
168+
extensions: migrate
169+
namespace: azure.mgmt.migrate
170+
package-name: azure-mgmt-migrate
171+
az-output-folder: $(azure-cli-extension-folder)/src/migrate
172+
python-sdk-output-folder: "$(az-output-folder)/azext_migrate/vendored_sdks/migrate"
173+
```
174+
175+
``` yaml $(az) && $(package-offazure)
176+
az:
177+
extensions: offazure
178+
namespace: azure.mgmt.offazure
179+
package-name: azure-mgmt-offazure
180+
az-output-folder: $(azure-cli-extension-folder)/src/offazure
181+
python-sdk-output-folder: "$(az-output-folder)/azext_offazure/vendored_sdks/offazure"
182+
```
183+
~~~
184+
185+
Finally, you need to prepare the readme.python.md and readme.cli.md
186+
187+
~~~
188+
// in readme.python.md file
189+
190+
## Python
191+
192+
``` yaml $(python)
193+
python:
194+
azure-arm: true
195+
license-header: MICROSOFT_MIT_NO_VERSION
196+
payload-flattening-threshold: 2
197+
clear-output-folder: true
198+
batch:
199+
- package-migrate: true
200+
- package-offazure: true
201+
```
202+
203+
``` yaml $(python) && $(package-migrate)
204+
python:
205+
package-version: 0.1.0
206+
namespace: azure.mgmt.migrate
207+
package-name: azure-mgmt-migrate
208+
basic-setup-py: true
209+
output-folder: $(python-sdks-folder)/migrate/azure-mgmt-migrate
210+
```
211+
212+
``` yaml $(python) && $(package-offazure)
213+
python:
214+
package-version: 0.1.0
215+
namespace: azure.mgmt.offazure
216+
package-name: azure-mgmt-offazure
217+
basic-setup-py: true
218+
output-folder: $(python-sdks-folder)/offazure/azure-mgmt-offazure
219+
```
220+
~~~
221+
222+
~~~
223+
// in readme.cli.md file
224+
225+
``` yaml
226+
# add any configuration here for all CLI languages
227+
# refer to the faq.md for more details
228+
229+
~~~
230+
231+
232+
## Run codegen
233+
After configure all the readme files, autorest can be used to generate SDK.
234+
~~~
235+
autorest --az --use=@autorest/az@latest /home/qiaozha/code/azure-rest-api-specs/specification/storage/resource-manager/readme.md --azure-cli-extension-folder=../azure-cli-extensions
236+
~~~
237+
238+
## Advance Usage
239+
240+
For advance usage of CLI Codegen, Please refer to [autorest.az doc](https://github.com/Azure/autorest.az/tree/master/doc)

‎documentation/samplefiles/readme.az.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## AZ
2+
3+
These settings apply only when `--az` is specified on the command line.
4+
5+
For new Resource Provider. It is highly recommended to onboard Azure CLI extensions. There's no differences in terms of customer usage.
6+
7+
``` yaml $(az) && $(target-mode) != 'core'
8+
az:
9+
extensions: [[ServiceName]]
10+
namespace: azure.mgmt.[[ServiceName]]
11+
package-name: azure-mgmt-[[ServiceName]]
12+
az-output-folder: $(azure-cli-extension-folder)/src/[[ServiceName]]
13+
python-sdk-output-folder: "$(az-output-folder)/azext_[[ServiceName]]/vendored_sdks/[[ServiceName]]"
14+
# add additinal configuration here specific for Azure CLI
15+
# refer to the faq.md for more details
16+
```
17+
18+
19+
20+
This is for command modules that already in azure cli main repo.
21+
``` yaml $(az) && $(target-mode) == 'core'
22+
az:
23+
extensions: [[ServiceName]]
24+
namespace: azure.mgmt.[[ServiceName]]
25+
package-name: azure-mgmt-[[ServiceName]]
26+
az-output-folder: $(azure-cli-folder)/src/azure-cli/azure/cli/command_modules/[[ServiceName]]
27+
python-sdk-output-folder: "$(az-output-folder)/vendored_sdks/[[ServiceName]]"
28+
```

‎documentation/samplefiles/readme.cli.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
## CLI Common Settings for all the command line tools

‎documentation/samplefiles/readme.python.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,38 @@
33
These settings apply only when `--python` is specified on the command line.
44
Please also specify `--python-sdks-folder=<path to the root directory of your azure-sdk-for-python clone>`.
55

6+
67
``` yaml $(python)
8+
python:
9+
azure-arm: true
10+
license-header: MICROSOFT_MIT_NO_VERSION
11+
package-name: azure-mgmt-[[ServiceName]]
12+
no-namespace-folders: true
13+
package-version: 1.0.0b1
14+
```
15+
16+
``` yaml $(python-mode) == 'update'
17+
python:
18+
output-folder: $(python-sdks-folder)/[[ServiceName]]/azure-mgmt-[[ServiceName]]/azure/mgmt/[[ServiceName]]
19+
```
20+
``` yaml $(python-mode) == 'create'
21+
python:
22+
basic-setup-py: true
23+
output-folder: $(python-sdks-folder)/[[ServiceName]]/azure-mgmt-[[ServiceName]]
24+
```
25+
26+
``` yaml $(python) && $(track2)
727
azure-arm: true
828
license-header: MICROSOFT_MIT_NO_VERSION
929
package-name: azure-mgmt-[[ServiceName]]
1030
no-namespace-folders: true
1131
package-version: 1.0.0b1
1232
```
1333
14-
``` yaml $(python-mode) == 'update'
34+
``` yaml $(python-mode) == 'update' && $(track2)
1535
output-folder: $(python-sdks-folder)/[[ServiceName]]/azure-mgmt-[[ServiceName]]/azure/mgmt/[[ServiceName]]
1636
```
17-
``` yaml $(python-mode) == 'create'
37+
``` yaml $(python-mode) == 'create' && $(track2)
1838
basic-setup-py: true
1939
output-folder: $(python-sdks-folder)/[[ServiceName]]/azure-mgmt-[[ServiceName]]
2040
```

‎documentation/samplefiles/samplereadme.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,11 @@ swagger-to-sdk:
5656
- repo: azure-resource-manager-schemas
5757
after_scripts:
5858
- node sdkauto_afterscript.js [[ServiceName]]/resource-manager
59+
- repo: azure-cli-extensions
5960
```
61+
## Az
62+
63+
See configuration in [readme.az.md](./readme.az.md)
6064

6165
## Go
6266

0 commit comments

Comments
 (0)