add-cli-readme-files-template (Azure#12137)

documentation/code-gen/configure-cli.md

@@ -0,0 +1,240 @@
+# Readme Configuration Guide for Azure CLI 
+This file describe how to configure readme files to make it available for Azure CLI code generation.
+
+## Common Configuration
+In order to use cli codegen. We need readme.az.md and readme.cli.md and readme.python.md to be ready.  
+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.  
+and the readme.az.md is specific configuration for Azure CLI. 
+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.
+
+
+### Basic Information
+Configure package title/description/tag.
+~~~~
+// file: readme.md
+
+``` yaml
+title: xxxxConfigurationClient
+description: xxxx Configuration Client
+openapi-type: arm
+tag: package-xxxx-xx-xx
+```
+~~~~
+
+### tag
+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.
+A tag can contains a bunch of swagger files which are used to generate the SDK. 
+
+The name of a tag should be in form of package-yyyy-mm-dd[-xxx], for example below tag names are available:
+- package-2020-02-03
+- package-2020-03-22-preview
+- package-2020-05-03-only
+
+while the below tag names are invalid names:
+- 2020-03-04
+- package-preview-2020-03-04
+
+A tag can be configured like below:
+~~~~
+// file: readme.md
+
+
+### Tag: package-2019-12-01
+
+These settings apply only when `--tag=package-2019-12-01` is specified on the command line.
+
+``` yaml $(tag) == 'package-2019-12-01'
+input-file:
+- Microsoft.Compute/stable/2019-12-01/compute.json
+- Microsoft.Compute/stable/2019-12-01/runCommands.json
+- Microsoft.Compute/stable/2019-12-01/gallery.json
+```
+~~~~
+
+
+## Swagger to SDK
+To make Azure SDK for Javascript (Typescript) can be generated from the tag, swagger-to-sdk need to be configured:
+
+~~~
+// file: readme.md
+
+## Swagger to SDK
+
+This section describes what SDK should be generated by the automatic system.
+This is not used by Autorest itself.
+
+``` yaml $(swagger-to-sdk)
+swagger-to-sdk:
+  - repo: azure-cli-extensions
+  - ...
+
+
+## AZ
+
+See configuration in [readme.az.md](./readme.az.md)
+~~~
+
+## Az Configuration
+Az dedicated configurations are configured in readme.az.md.
+the typical package-name is usually like `@azure/arm-xxx`  where the xxx is related with the service name.   
+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.  
+A typical readme.az.md is like this: 
+~~~
+// file: readme.az.md
+
+## AZ
+
+These settings apply only when `--az` is specified on the command line.
+
+``` yaml $(az) && $(target-mode) != 'core'
+az:
+    extensions: communication
+    namespace: azure.mgmt.communication
+    package-name: azure-mgmt-communication
+az-output-folder: $(azure-cli-extension-folder)/src/communication
+python-sdk-output-folder: "$(az-output-folder)/azext_communication/vendored_sdks/communication"
+# add additinal configuration here specific for Azure CLI
+# refer to the faq.md for more details
+```
+
+~~~
+
+## Multi-api
+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. 
+
+## Multi-packages 
+The batch is a tag list which are used in the one RP has multi-package scenarios. For example, 
+the Migrate RP has two independent packages like migrate and offazure.  
+First of all, you need to have different yaml block for each package to define the default tag for that specific package.
+~~~
+// file: readme.md
+## Configuration
+
+### Basic Information
+
+These are the global settings for the Resource API.
+
+``` yaml
+openapi-type: arm
+```
+
+``` yaml $(package-migrate)
+tag: package-migrate-2019-10
+```
+
+``` yaml $(package-offazure)
+tag: package-offazure-2020-01
+```
+
+~~~
+Then for each default tag, you can define the input swagger like normal tag.
+~~~
+
+### Tag: package-migrate-2019-10
+
+These settings apply only when `--tag=package-migrate-2019-10` is specified on the command line.
+
+``` yaml $(tag) == 'package-migrate-2019-10'
+input-file:
+- Microsoft.Migrate/stable/2019-10-01/migrate.json
+```
+
+### Tag: package-offazure-2020-01
+
+These settings apply only when `--tag=package-offazure-2020-01` is specified on the command line.
+
+``` yaml $(tag) == 'package-offazure-2020-01'
+input-file:
+- Microsoft.OffAzure/stable/2020-01-01/migrate.json
+```
+
+~~~
+
+Thirdly, in your readme.az.md you should include what packages you want to include in the Azure CLI.
+And in each package's section define the default package name output folder in azure-cli-extensions repo etc.
+
+~~~
+## AZ
+
+These settings apply only when `--az` is specified on the command line.
+``` yaml $(az)
+batch:
+    - package-migrate: true
+    - package-offazure: true
+```
+
+``` yaml $(az) && $(package-migrate)
+az:
+  extensions: migrate
+  namespace: azure.mgmt.migrate
+  package-name: azure-mgmt-migrate
+az-output-folder: $(azure-cli-extension-folder)/src/migrate
+python-sdk-output-folder: "$(az-output-folder)/azext_migrate/vendored_sdks/migrate"
+```
+
+``` yaml $(az) && $(package-offazure)
+az:
+  extensions: offazure
+  namespace: azure.mgmt.offazure
+  package-name: azure-mgmt-offazure
+az-output-folder: $(azure-cli-extension-folder)/src/offazure
+python-sdk-output-folder: "$(az-output-folder)/azext_offazure/vendored_sdks/offazure"
+```
+~~~
+
+Finally, you need to prepare the readme.python.md and readme.cli.md
+
+~~~
+// in readme.python.md file
+
+## Python
+
+``` yaml $(python)
+python:
+  azure-arm: true
+  license-header: MICROSOFT_MIT_NO_VERSION
+  payload-flattening-threshold: 2
+  clear-output-folder: true
+batch:
+  - package-migrate: true
+  - package-offazure: true
+```
+
+``` yaml $(python) && $(package-migrate)
+python:
+  package-version: 0.1.0
+  namespace: azure.mgmt.migrate
+  package-name: azure-mgmt-migrate
+  basic-setup-py: true
+  output-folder: $(python-sdks-folder)/migrate/azure-mgmt-migrate
+```
+
+``` yaml $(python) && $(package-offazure)
+python:
+  package-version: 0.1.0
+  namespace: azure.mgmt.offazure
+  package-name: azure-mgmt-offazure
+  basic-setup-py: true
+  output-folder: $(python-sdks-folder)/offazure/azure-mgmt-offazure
+```
+~~~
+
+~~~
+// in readme.cli.md file
+
+``` yaml
+# add any configuration here for all CLI languages
+# refer to the faq.md for more details
+
+~~~
+
+
+## Run codegen
+After configure all the readme files, autorest can be used to generate SDK.
+~~~
+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
+~~~
+
+## Advance Usage 
+
+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

@@ -0,0 +1,28 @@
+## AZ
+
+These settings apply only when `--az` is specified on the command line.
+
+For new Resource Provider. It is highly recommended to onboard Azure CLI extensions. There's no differences in terms of customer usage. 
+
+``` yaml $(az) && $(target-mode) != 'core'
+az:
+    extensions: [[ServiceName]]
+    namespace: azure.mgmt.[[ServiceName]]
+    package-name: azure-mgmt-[[ServiceName]]
+az-output-folder: $(azure-cli-extension-folder)/src/[[ServiceName]]
+python-sdk-output-folder: "$(az-output-folder)/azext_[[ServiceName]]/vendored_sdks/[[ServiceName]]"
+# add additinal configuration here specific for Azure CLI
+# refer to the faq.md for more details
+```
+
+
+
+This is for command modules that already in azure cli main repo. 
+``` yaml $(az) && $(target-mode) == 'core'
+az:
+  extensions: [[ServiceName]]
+  namespace: azure.mgmt.[[ServiceName]]
+  package-name: azure-mgmt-[[ServiceName]]
+az-output-folder: $(azure-cli-folder)/src/azure-cli/azure/cli/command_modules/[[ServiceName]]
+python-sdk-output-folder: "$(az-output-folder)/vendored_sdks/[[ServiceName]]"
+``` 

documentation/samplefiles/readme.cli.md

@@ -0,0 +1 @@
+## CLI Common Settings for all the command line tools

documentation/samplefiles/readme.python.md

@@ -3,18 +3,38 @@
 These settings apply only when `--python` is specified on the command line.
 Please also specify `--python-sdks-folder=<path to the root directory of your azure-sdk-for-python clone>`.
 
+
 ``` yaml $(python)
+python: 
+    azure-arm: true
+    license-header: MICROSOFT_MIT_NO_VERSION
+    package-name: azure-mgmt-[[ServiceName]]
+    no-namespace-folders: true
+    package-version: 1.0.0b1
+```
+
+``` yaml $(python-mode) == 'update'
+python:
+    output-folder: $(python-sdks-folder)/[[ServiceName]]/azure-mgmt-[[ServiceName]]/azure/mgmt/[[ServiceName]]
+```
+``` yaml $(python-mode) == 'create'
+python:
+    basic-setup-py: true
+    output-folder: $(python-sdks-folder)/[[ServiceName]]/azure-mgmt-[[ServiceName]]
+```
+
+``` yaml $(python) && $(track2)
 azure-arm: true
 license-header: MICROSOFT_MIT_NO_VERSION
 package-name: azure-mgmt-[[ServiceName]]
 no-namespace-folders: true
 package-version: 1.0.0b1
 ```
 
-``` yaml $(python-mode) == 'update'
+``` yaml $(python-mode) == 'update' && $(track2)
 output-folder: $(python-sdks-folder)/[[ServiceName]]/azure-mgmt-[[ServiceName]]/azure/mgmt/[[ServiceName]]
 ```
-``` yaml $(python-mode) == 'create'
+``` yaml $(python-mode) == 'create' && $(track2)
 basic-setup-py: true
 output-folder: $(python-sdks-folder)/[[ServiceName]]/azure-mgmt-[[ServiceName]]
 ```

documentation/samplefiles/samplereadme.md

@@ -56,7 +56,11 @@ swagger-to-sdk:
   - repo: azure-resource-manager-schemas
     after_scripts:
       - node sdkauto_afterscript.js [[ServiceName]]/resource-manager
+  - repo: azure-cli-extensions
 ```
+## Az
+
+See configuration in [readme.az.md](./readme.az.md)
 
 ## Go