Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update client generation documentation #1294

Merged
merged 6 commits into from
Aug 16, 2024
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# How to generate DPG
# How to generate client libraries

This page documents how to build a Data-Plane SDK from your TYPESPEC specification. For an overview of the whole process from initial API design to shipping SDKs, please visit https://aka.ms/azsdk/dpcodegen.
This page documents how to build a client library from your TYPESPEC specification. For an overview of the whole process from initial API design to shipping SDKs, please visit https://aka.ms/azsdk/dpcodegen.

The best documentation on how to generate can found using those links:

Expand All @@ -15,11 +15,11 @@ The best documentation on how to generate can found using those links:

At a glance, add your emitter name to your `package.json`, along with the right options in the `tspconfig.yaml`.

> **NOTE:** It may be complicated to generate all languages from the same folder at the moment as DPG and `typespec-azure-core` are still in preview.
> It's recommended that you keep each `package.json` with a unique language emitter, as they are likely to conflict, until all emitters and `typespec-azure-core`
> **NOTE:** It may be complicated to generate all languages from the same folder at the moment as the emitters and TypeSpec libraries, such as `typespec-azure-core` and `typespec-resource-manager` are still in preview.
> It's recommended that you keep each `package.json` with a unique language emitter, as they are likely to conflict, until all emitters and the TypeSpec libraries
> reach their first stable release.

Update your `package.json` to contain dependencies on DPG language emitter(s). Don't forget to do `npm install` after an update of the file:
Update your `package.json` to contain dependencies on the language emitter(s). Don't forget to do `npm install` after an update of the file:

```json
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ import TabItem from "@theme/TabItem";

# Setup for SDK customization

This page explains how to setup customization of DPG generator if necessary.
This page explains how to setup customization of a generator if necessary.

Your `package.json` needs to contains a link to the customization library for dpg, called `typespec-client-generator-core`:
Your `package.json` needs to contains a link to the customization library, `typespec-client-generator-core`:

```json
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ import TabItem from "@theme/TabItem";

# Client hierarchy

This page documents the default client hierarchy behavior as well as how to customize clients in DPG. For an overview of the setup, please visit the previous page.
This page documents the default client hierarchy behavior as well as how to customize clients. For an overview of the setup, please visit the previous page.

JS RLC is not in the business of customization. it will ignore client.tsp and the follow scenarios will not have impact on the JS RLC user experiences. In this context, TypeScript part means JS DPG.
JS RLC is not in the business of customization. it will ignore client.tsp and the follow scenarios will not have impact on the JS RLC user experiences. In this context, TypeScript part means JS convenience emitter.
catalinaperalta marked this conversation as resolved.
Show resolved Hide resolved

## Default behavior

Expand Down Expand Up @@ -288,7 +288,7 @@ For this section, we will assume that you have service called `PetStore` in the

### Renaming the single client

This can be achieved with the augment operator and the DPG package
This can be achieved with the augment operator and the emitter package

<Tabs>
<TabItem value="typespec" label="TypeSpec" default>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import TabItem from "@theme/TabItem";

# Convenient method generation

This page documents how to customize method generations in DPG. For an overview of the setup, please visit the setup page.
This page documents how to customize method generation for the emitters. For an overview of the setup, please visit the setup page.

## Default behaviors

Expand Down Expand Up @@ -114,7 +114,7 @@ For fine tuning, the set of decorators `@protocolAPI` and `@convenientAPI` can b

### Shifting the generation of protocol and convenience on and off

This can be achieved with the augment operator and the DPG package
This can be achieved with the augment operator and the emitter package

<Tabs>
<TabItem value="typespec" label="TypeSpec" default>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import TabItem from "@theme/TabItem";

# Client renaming

This page documents how to customize names for client generations in DPG. For an overview of the setup, please visit the setup page.
This page documents how to customize names for client generation. For an overview of the setup, please visit the setup page.

:::note
The TypeSpec compiler provides an `@encodedName` decorator that allows changing the name of the property for a given serialization format.
Expand Down Expand Up @@ -113,7 +113,7 @@ Renames in the context of models can be done on the model name and the attribute

Language target takes priority over `client` target.

> **NOTE:** As model name do not get serialized as JSON, sometimes the best choice is to rename the main TYPESPEC for clarity. Talk to your DPG contact is you're unsure
> **NOTE:** As model name do not get serialized as JSON, sometimes the best choice is to rename the main TYPESPEC for clarity. Talk to your emitter contact is you're unsure
> if you should rename the model in the main TYPESPEC or customize it.

<Tabs>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import TabItem from "@theme/TabItem";

# One path for multiple input/output

This page documents DPG behavior and customization when you use union operator `|` or `@sharedRoute` to express multiple input/output for a given path.
This page documents emitter behavior and customization when you use union operator `|` or `@sharedRoute` to express multiple input/output for a given path.

## Default behaviors

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ public partial class Foo : IUtf8JsonSerializable, IJsonModel<Foo>
</TabItem>
<TabItem value="java" label="Java" >

In Java, `@flattenProperty` have no effect on data-plane libraries.
In Java, `@flattenProperty` have no effect on generated libraries.

```java
@Fluent
Expand Down Expand Up @@ -247,7 +247,7 @@ model Animal is Record<unknown> {
</TabItem>
<TabItem value="python" label="Python">

Python DPG model is original designed to support adding any additional properties.
Python models are designed to support adding any additional properties.

```python
from .. import _model_base
Expand Down Expand Up @@ -396,7 +396,7 @@ model Animal {
</TabItem>
<TabItem value="python" label="Python">

Python DPG model is original designed to support adding any additional properties.
Python models are designed to support adding any additional properties.

```python
from typing import Any
Expand Down Expand Up @@ -606,7 +606,7 @@ model Animal {
</TabItem>
<TabItem value="python" label="Python">

Python DPG model is original designed to support adding any additional properties.
Python models are designed to support adding any additional properties.

```python
from .. import _model_base
Expand Down Expand Up @@ -726,7 +726,7 @@ model Animal {
</TabItem>
<TabItem value="python" label="Python">

Python DPG model is original designed to support adding any additional properties.
Python models are designed to support adding any additional properties.

```python
from .. import _model_base
Expand Down
Loading