Add the introduction of emitters for sdk clients. (#5663)

To resolve #5339 Add the introduction to describe the location, the configuration and how to run the client emitters for Java, Python, JS and .NET. The doc currently only contain the common content and it needs the contribution for all language owners. cc @lmazuel --------- Co-authored-by: Yuchao Yan <[email protected]> Co-authored-by: Weidong Xu <[email protected]> Co-authored-by: Mark Cowlishaw <[email protected]> Co-authored-by: Mary Gao <[email protected]> Co-authored-by: Laurent Mazuel <[email protected]> Co-authored-by: Timothee Guerin <[email protected]>
microsoft · Feb 12, 2025 · d77feba · d77feba
1 parent 2b9d287
commit d77feba
Show file tree

Hide file tree

Showing 2 changed files with 145 additions and 0 deletions.
diff --git a/website/src/content/current-sidebar.ts b/website/src/content/current-sidebar.ts
@@ -139,6 +139,10 @@ const sidebar: SidebarItem[] = [
       createLibraryReferenceStructure("emitters/protobuf", "Protobuf", false, [
         "emitters/protobuf/guide",
       ]),
+      {
+        label: "Clients",
+        items: ["emitters/clients/introduction"],
+      },
     ],
   },
   {

diff --git a/website/src/content/docs/docs/emitters/clients/introduction.mdx b/website/src/content/docs/docs/emitters/clients/introduction.mdx
@@ -0,0 +1,141 @@
+---
+title: Client Emitters
+---
+
+import { Aside, Steps } from "@astrojs/starlight/components";
+
+## How to Use Emitters to Generate HTTP Clients from TypeSpec
+
+### Introduction
+
+This guide will walk you through the process of using different client emitters (JavaScript, Python, Java, .NET) to generate HTTP clients from TypeSpec. Please note that all client emitters are currently in **preview** and are subject to changes in future versions.
+
+By following this guide, you will learn:
+
+1. How to set up client emitters in `package.json`.
+2. Update the client emitter configurations in `tspconfig.yaml`.
+3. How to generate HTTP clients for each specific programming language.
+
+## Location of All Client Emitters
+
+The client emitters are defined in the `package.json` file within your project.
+
+| **Emitter Name**             | **Language** | **Version**                                                    |
+| ---------------------------- | ------------ | -------------------------------------------------------------- |
+| @azure-tools/typespec-ts     | JavaScript   | ![](https://img.shields.io/npm/v/@azure-tools/typespec-ts)     |
+| @typespec/http-client-python | Python       | ![](https://img.shields.io/npm/v/@typespec/http-client-python) |
+| @typespec/http-client-java   | Java         | ![](https://img.shields.io/npm/v/@typespec/http-client-java)   |
+| @typespec/http-client-csharp | .NET         | ![](https://img.shields.io/npm/v/@typespec/http-client-csharp) |
+
+Below is an example of the `package.json` snippet where client emitters are defined:
+
+```json
+  "dependencies": {
+    "@typespec/http-client-csharp": "^0.1.9-alpha.20250113.2",
+    "@typespec/http-client-java": "^0.1.9",
+    "@typespec/http-client-python": "^0.6.6",
+    "@azure-tools/typespec-ts": "^0.38.1",
+  }
+```
+
+## Client Emitter Settings
+
+This part provides an overview of the common and language-specific settings for each client emitter. These settings are stored in the `tspconfig.yaml` file.
+
+### Common Configuration Options
+
+The below option applies to all client emitters.
+
+- `emitter-output-dir`: Defines where the generated SDK files will be stored.
+
+### JavaScript Client Emitter Settings
+
+JavaScript generally requires minimal configuration. However, it is recommended to provide `packageDetails` for package metadata, which is used in `package.json` and `README.md` files.
+
+#### packageDetails
+
+Provide the metadata for `package.json`, `README.md` information.
+
+| Property    | Description                                                            |
+| ----------- | ---------------------------------------------------------------------- |
+| name        | Package name used in `package.json`                                    |
+| description | Package description used in `package.json` file                        |
+| version     | Detailed version for your package, the default value is `1.0.0-beta.1` |
+
+Example configuration:
+
+```yaml
+packageDetails:
+  name: "${your_package_name}"
+  version: 1.0.0
+```
+
+### Java Client Emitter Settings
+
+#### Prerequisites
+
+Before using the Java client emitter, ensure the following dependencies are installed:
+
+- **Java 17 or later** - [Download here](https://docs.microsoft.com/java/openjdk/download)  
+  _(Verify installation with `java --version`)_
+- **Maven** - [Download here](https://maven.apache.org/download.cgi)  
+  _(Verify installation with `mvn --version`)_
+
+### .NET Client Emitter Settings
+
+> _(Details to be added by .NET contributors)_
+
+## Running Language-Specific Emitters in CLI
+
+<Steps>
+
+1. Ensure that your package.json file is correctly configured to include the necessary dependencies for running the emitters
+
+2. Update the tspconfig.yaml file for properly configured for the language-specific emitter.
+
+   ```yaml
+   emit:
+     - "@typespec/http-client-csharp"
+     - "@typespec/http-client-java"
+     - "@typespec/http-client-python"
+     - "@azure-tools/typespec-ts"
+   options:
+     "@typespec/http-client-csharp":
+       emitter-output-dir: "{project-root}/clients/dotnet"
+     "@typespec/http-client-java":
+       emitter-output-dir: "{project-root}/clients/java"
+     "@typespec/http-client-python":
+       emitter-output-dir: "{project-root}/clients/python"
+     "@azure-tools/typespec-ts":
+       emitter-output-dir: "{project-root}/clients/javascript"
+       packageDetails:
+         name: "${your_package_name}"
+         version: 1.0.0
+   ```
+
+3. Once the package.json and tspconfig.yaml files are updated, you need to install all required dependencies by running the following command in the project root:
+
+   ```bash
+   tsp install
+   ```
+
+4. Run the emitter to compile your TypeScript code into the desired language. Use the following command to trigger the emitter and compile your project:
+
+   ```bash
+   tsp compile {path to main.tsp}/main.tsp
+   ```
+
+</Steps>
+
+## Disclaimer
+
+<Aside>
+
+**All client emitters are in preview**. These emitters are actively being developed and may experience changes or updates that could affect their functionality. Please follow the official documentation for the latest updates.
+
+- [TypeSpec CSharp emitter library](https://github.com/microsoft/typespec/blob/main/packages/http-client-csharp/readme.md)
+- [TypeSpec Python emitter library](https://github.com/microsoft/typespec/blob/main/packages/http-client-python/README.md)
+- [TypeSpec Java emitter library](https://github.com/microsoft/typespec/blob/main/packages/http-client-java/README.md)
+- [TypeSpec JS emitter library](https://github.com/Azure/autorest.typescript/blob/main/packages/typespec-ts/README.md)
+
+</Aside>