add doc for typescript md

documentation/code-gen/configure-typescript-sdk.md

@@ -0,0 +1,235 @@
+# Readme Configuration Guide for Azure SDK for Javascript (Typescript)
+This file describe how to configure readme files to make it available for Azure SDK for Javascript (Typescript) code generation.
+
+## Common Configuration
+Configure basic package information.
+
+### 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-sdk-for-js
+  - ...
+
+
+## Typescript
+
+See configuration in [readme.typescript.md](./readme.typescript.md)
+~~~
+
+## Typescript Configuration
+Typescript dedicated configurations are configured in readme.typescript.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.typescript.md is like this: 
+~~~
+// file: readme.typescript.md
+
+## TypeScript
+
+These settings apply only when `--typescript` is specified on the command line.
+Please also specify `--typescript-sdks-folder=<path to root folder of your azure-sdk-for-js clone>`.
+
+``` yaml $(typescript)
+typescript:
+  azure-arm: true
+  package-name: "@azure/arm-apimanagement"
+  output-folder: "$(typescript-sdks-folder)/sdk/apimanagement/arm-apimanagement"
+  clear-output-folder: true
+  generate-metadata: true
+```
+
+~~~
+
+## Multi-api
+Currently the Azure SDK for Javascript (Typescript) doesn't support multi-api which means each operation contained in one package should only contains one api-version's. and Azure SDK for Javascript (Typescript) only supports single api package.
+
+## Multi-packages 
+The batch is a tag list which are used in the one RP has multi-package scenarios. For example, 
+the Resources RP has several independent packages like features, lock, policy.  
+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-features)
+tag: package-features-2015-12
+```
+
+``` yaml $(package-locks)
+tag: package-locks-2016-09
+```
+
+``` yaml $(package-policy)
+tag: package-policy-2019-09
+```
+
+``` yaml $(package-resources)
+tag: package-resources-2020-06
+```
+
+~~~
+Then for each default tag, you can define the input swagger like normal tag.
+~~~
+
+### Tag: package-features-2015-12
+
+These settings apply only when `--tag=package-features-2015-12` is specified on the command line.
+
+``` yaml $(tag) == 'package-features-2015-12'
+input-file:
+- Microsoft.Features/stable/2015-12-01/features.json
+```
+
+### Tag: package-locks-2016-09
+
+These settings apply only when `--tag=package-locks-2016-09` is specified on the command line.
+
+``` yaml $(tag) == 'package-locks-2016-09'
+input-file:
+- Microsoft.Authorization/stable/2016-09-01/locks.json
+```
+
+### Tag: package-policy-2019-09
+
+These settings apply only when `--tag=package-policy-2019-09` is specified on the command line.
+
+``` yaml $(tag) == 'package-policy-2019-09'
+input-file:
+- Microsoft.Authorization/stable/2019-09-01/policyAssignments.json
+- Microsoft.Authorization/stable/2019-09-01/policyDefinitions.json
+- Microsoft.Authorization/stable/2019-09-01/policySetDefinitions.json
+
+# Needed when there is more than one input file
+override-info:
+  title: PolicyClient
+```
+
+### Tag: package-resources-2020-06
+
+These settings apply only when `--tag=package-resources-2020-06` is specified on the command line.
+
+``` yaml $(tag) == 'package-resources-2020-06'
+input-file:
+- Microsoft.Resources/stable/2020-06-01/resources.json
+```
+~~~
+
+Finally, in your readme.typescript.md you should include what packages you want to include in the Azure SDK for Javascript (Typescript).
+And in each package's section define the default package name output folder in azure-sdk-for-js repo etc.
+
+~~~
+## TypeScript
+
+These settings apply only when `--typescript` is specified on the command line.
+Please also specify `--typescript-sdks-folder=<path to root folder of your azure-sdk-for-js clone>`.
+
+```yaml $(typescript) && !$(profile)
+typescript:
+  azure-arm: true
+  batch: true
+  generate-metadata: true
+batch:
+  - package-features: true
+  - package-locks: true
+  - package-policy: true
+  - package-resources: true
+```
+
+```yaml $(typescript) && $(package-features) && !$(profile)
+typescript:
+  package-name: "@azure/arm-features"
+  output-folder: "$(typescript-sdks-folder)/sdk/features/arm-features"
+  clear-output-folder: true
+```
+
+```yaml $(typescript) && $(package-locks) && !$(profile)
+typescript:
+  package-name: "@azure/arm-locks"
+  output-folder: "$(typescript-sdks-folder)/sdk/locks/arm-locks"
+  clear-output-folder: true
+```
+
+```yaml $(typescript) && $(package-policy) && !$(profile)
+typescript:
+  package-name: "@azure/arm-policy"
+  output-folder: "$(typescript-sdks-folder)/sdk/policy/arm-policy"
+  clear-output-folder: true
+```
+
+```yaml $(typescript) && $(package-resources) && !$(profile)
+typescript:
+  package-name: "@azure/arm-resources"
+  output-folder: "$(typescript-sdks-folder)/sdk/resources/arm-resources"
+  clear-output-folder: true
+```
+
+~~~
+
+
+## Run codegen
+After configure all the readme files, autorest can be used to generate SDK.
+~~~
+autorest --typescript --typescript-sdks-folder=/home/qiaozha/code/azure-sdk-for-js --license-header=MICROSOFT_MIT_NO_VERSION /home/qiaozha/code/azure-rest-api-specs/specification/storage/resource-manager/readme.md --use=@microsoft.azure/autorest.typescript@4.2.2
+~~~