Skip to content

Commit

Permalink
[Doc]update doc for configure-python-sdk (Azure#18618)
Browse files Browse the repository at this point in the history
* update doc

* Update configure-python-sdk.md

* Update configure-python-sdk.md

* Update configure-python-sdk.md
  • Loading branch information
BigCat20196 authored and FredericHeem committed May 16, 2022
1 parent a464ab2 commit e52cd11
Showing 1 changed file with 15 additions and 68 deletions.
83 changes: 15 additions & 68 deletions documentation/code-gen/configure-python-sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
- ...
Expand All @@ -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=<path to the root directory of your azure-sdk-for-python clone>`.
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=<path to the root directory of your azure-sdk-for-python clone>`.
``` 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.
Expand All @@ -170,23 +143,16 @@ 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
- tag: package-2020-05-01-only
- 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
```
~~~
Expand All @@ -201,40 +167,21 @@ 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=<path to the root directory of your azure-sdk-for-python clone>`.

``` 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

~~~
> 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
~~~
~~~

0 comments on commit e52cd11

Please sign in to comment.