From e52cd11e6181213371e3872949b15b64324e6283 Mon Sep 17 00:00:00 2001 From: Jiefeng Chen <51037443+BigCat20196@users.noreply.github.com> Date: Wed, 20 Apr 2022 16:44:01 +0800 Subject: [PATCH] [Doc]update doc for configure-python-sdk (#18618) * update doc * Update configure-python-sdk.md * Update configure-python-sdk.md * Update configure-python-sdk.md --- .../code-gen/configure-python-sdk.md | 83 ++++--------------- 1 file changed, 15 insertions(+), 68 deletions(-) diff --git a/documentation/code-gen/configure-python-sdk.md b/documentation/code-gen/configure-python-sdk.md index 2ffc81afbbcf..66895a00153d 100644 --- a/documentation/code-gen/configure-python-sdk.md +++ b/documentation/code-gen/configure-python-sdk.md @@ -86,8 +86,7 @@ This is not used by Autorest itself. ``` yaml $(swagger-to-sdk) swagger-to-sdk: - - repo: azure-sdk-for-python // for track1 SDK - - repo: azure-sdk-for-python-track2 // for track2 SDK + - repo: azure-sdk-for-python-track2 - ... @@ -103,58 +102,32 @@ A typical readme.python.md is like this: ~~~ // file: readme.python.md - ## Python These settings apply only when `--python` is specified on the command line. Please also specify `--python-sdks-folder=`. Use `--python-mode=update` if you already have a setup.py and just want to update the code itself. -``` yaml !$(track2) // For track1: basic Python package information -python-mode: create -python: - azure-arm: true - license-header: MICROSOFT_MIT_NO_VERSION - payload-flattening-threshold: 2 - namespace: azure.mgmt.appconfiguration - package-name: azure-mgmt-appconfiguration - package-version: 0.1.0 - clear-output-folder: true -``` - -``` yaml $(python-mode) == 'update' && !$(track2) -python: - no-namespace-folders: true - output-folder: $(python-sdks-folder)/appconfiguration/azure-mgmt-appconfiguration/azure/mgmt/appconfiguration -``` -``` yaml $(python-mode) == 'create' && !$(track2) -python: - basic-setup-py: true - output-folder: $(python-sdks-folder)/appconfiguration/azure-mgmt-appconfiguration -``` +## Python -These settings apply only when `--track2` is specified on the command line. +These settings apply only when `--python` is specified on the command line. +Please also specify `--python-sdks-folder=`. -``` yaml $(track2) // For track2: basic Python package information +``` yaml $(python) azure-arm: true license-header: MICROSOFT_MIT_NO_VERSION -package-name: azure-mgmt-appconfiguration -no-namespace-folders: true -package-version: 0.1.0 +package-name: azure-mgmt-[[ServiceName]] +namespace: azure.mgmt.[[ServiceName]] +package-version: 1.0.0b1 +clear-output-folder: true ``` -``` yaml $(python-mode) == 'update' && $(track2) +``` yaml $(python) no-namespace-folders: true -output-folder: $(python-sdks-folder)/appconfiguration/azure-mgmt-appconfiguration/azure/mgmt/appconfiguration +output-folder: $(python-sdks-folder)/[[ServiceName]]/azure-mgmt-[[ServiceName]]/azure/mgmt/[[ServiceName]] ``` -``` yaml $(python-mode) == 'create' && $(track2) -basic-setup-py: true -output-folder: $(python-sdks-folder)/appconfiguration/azure-mgmt-appconfiguration -``` -~~~ - ## Multi-API Multi-API SDK is a package that support multiple REST api-versions. With Python multi-api SDK, the end user can assign api-version for REST calls explicitly; nevertheless, they can also use the default api-version which is choosed as the latest stable api-version. @@ -170,13 +143,7 @@ The batch is a tag list which are used in the multi-api package. For example: Generate all API versions currently shipped for this package -```yaml $(multiapi) && !$(track2) // For track1 -batch: - - tag: package-2020-06-01-only - - tag: package-2020-05-01-only -``` - -```yaml $(multiapi) && $(track2) // For track2 +```yaml $(multiapi) && $(python) clear-output-folder: true batch: - tag: package-2020-06-01-only @@ -184,9 +151,8 @@ batch: - multiapiscript: true ``` -``` yaml $(multiapiscript) && $(track2) // For track2 +``` yaml $(multiapiscript) && $(python) output-folder: $(python-sdks-folder)/compute/azure-mgmt-compute/azure/mgmt/compute/ -clear-output-folder: false perform-load: false ``` ~~~ @@ -201,35 +167,16 @@ Then, the output folder and namespace should be configured for each of the tag. These settings apply only when `--tag=package-2020-06-01-only --python` is specified on the command line. Please also specify `--python-sdks-folder=`. -``` yaml $(tag) == 'package-2020-06-01-only' && $(track2) // For track2 +``` yaml $(tag) == 'package-2020-06-01-only' && $(python) namespace: azure.mgmt.compute.v2020_06_01 output-folder: $(python-sdks-folder)/compute/azure-mgmt-compute/azure/mgmt/compute/v2020_06_01 ``` ~~~ -### multi-api init script -For track1, multi-api init script need to be configured in readme.md. For example: - -~~~ -// file: readme.md - -swagger-to-sdk: - - repo: azure-sdk-for-python - after_scripts: - - python ./scripts/multiapi_init_gen.py azure-mgmt-compute -~~~ - - ## Run codegen After configure all the readme files, autorest can be used to generate SDK. -### Track1 (for Autorest V2) -Track1 SDK is based on AutoRest version V2 that's going to be replaced by version V3. - -~~~ -> autorest --keep-version-file --multiapi --no-async --python --python-mode=update --python-sdks-folder=C:\ZZ\projects\codegen\azure-sdk-for-python\sdk --use=@microsoft.azure/autorest.python@~4.0.71 --version=V2 ..\azure-rest-api-specs\specification\appconfiguration\resource-manager\readme.md -~~~ ### Track2 (for latest Autorest) Track 2 is based on the latest AutoRest code generator @@ -237,4 +184,4 @@ Track 2 is based on the latest AutoRest code generator ~~~ > autorest --reset > autorest --python --track2 --use=@autorest/python@5.4.1 --python-sdks-folder=..\azure-sdk-for-python\sdk --multiapi --python-mode=update ..\azure-rest-api-specs\specification\appconfiguration\resource-manager\readme.md -~~~ \ No newline at end of file +~~~