Update website docs to reflect renaming the client generation docs (A…

…zure#1444) Pushing changes to the website package to reflect the changes made to the client generation documentation in this PR: Azure#1294 Co-authored-by: Catalina Peralta <[email protected]>
markcowl · Sep 7, 2024 · 9c5e8c4 · 9c5e8c4
1 parent 7b9a115
commit 9c5e8c4
Show file tree

Hide file tree

Showing 12 changed files with 671 additions and 35 deletions.
diff --git a/...DataPlane Generation - DPG/00howtogen.mdx → ...t/howtos/Client Generation/00howtogen.mdx b/...DataPlane Generation - DPG/00howtogen.mdx → ...t/howtos/Client Generation/00howtogen.mdx
@@ -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:
 
@@ -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
 {

diff --git a/...os/DataPlane Generation - DPG/01setup.mdx → ...test/howtos/Client Generation/01setup.mdx b/...os/DataPlane Generation - DPG/01setup.mdx → ...test/howtos/Client Generation/01setup.mdx
@@ -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
 {

diff --git a/...s/DataPlane Generation - DPG/02client.mdx → ...est/howtos/Client Generation/02client.mdx b/...s/DataPlane Generation - DPG/02client.mdx → ...est/howtos/Client Generation/02client.mdx
@@ -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 Modular Emitter.
 
 ## Default behavior
 
@@ -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>

diff --git a/...taPlane Generation - DPG/03convenient.mdx → ...howtos/Client Generation/03convenient.mdx b/...taPlane Generation - DPG/03convenient.mdx → ...howtos/Client Generation/03convenient.mdx
@@ -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
 
@@ -38,7 +38,6 @@ op GetModel is ResourceRead<OutputModel>;
 class OutputModel:
   name: str = rest_field(readonly=True)
 response: OutputModel = client.get(name="name")
-FIXME
 ```
 
 </TabItem>
@@ -114,7 +113,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>
@@ -198,9 +197,8 @@ The two possible value for the `Access` enum are `internal` and `public`.
 <TabItem value="python" label="Python">
 
 ```python
-class _GetModel:
-  ...
-# FIXME
+# can't import form models directly
+from petstorenamespace.models import GetModel # will report error
 ```
 
 </TabItem>

diff --git a/...DataPlane Generation - DPG/04renaming.mdx → ...t/howtos/Client Generation/04renaming.mdx b/...DataPlane Generation - DPG/04renaming.mdx → ...t/howtos/Client Generation/04renaming.mdx
@@ -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.
@@ -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>
@@ -214,9 +214,7 @@ using Azure.ClientGenerator.Core;
 ```python
 class InputModel:
   input_name: str = rest_field(rest_name="name", readonly=True)
-
-client.get_computed_model(name="name")
-# FIXME
+response: InputModel = client.get_computed_model(name="name")
 ```
 
 </TabItem>

diff --git a/...os/DataPlane Generation - DPG/05union.mdx → ...test/howtos/Client Generation/05union.mdx b/...os/DataPlane Generation - DPG/05union.mdx → ...test/howtos/Client Generation/05union.mdx
@@ -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
 
@@ -37,11 +37,11 @@ op completions(@body input: CompletionInput): CompletionResult;
 <TabItem value="python" label="Python">
 
 ```python
-def analyze(*, mode: Literal["strict", "lenient"], image: bytes) -> AnalyzeResult:
+def analyze(image: bytes, *, mode: Literal["strict", "lenient"]) -> AnalyzeResult:
   ...
 
 class CompletionInput:
-  input: str | List[str] = rest_field(readonly=True)
+  input: Union[str, List[str]] = rest_field(readonly=True)
 
 def completions(input: CompletionInput) -> CompletionResult:
   ...

diff --git a/...os/DataPlane Generation - DPG/06types.mdx → ...test/howtos/Client Generation/06types.mdx b/...os/DataPlane Generation - DPG/06types.mdx → ...test/howtos/Client Generation/06types.mdx
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -2372,7 +2372,8 @@ TODO;
 <TabItem value="java" label="Java" >
 
 ```java
-TODO
+// Internal implementation
+jsonWriter.writeStringField("prop", Objects.toString(this.value, null));
 ```
 
 </TabItem>