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

Add the introduction of emitters for sdk clients. #5663

Open
wants to merge 23 commits into
base: main
Choose a base branch
from
Open
Changes from 1 commit
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
9f7f5f4
Add the introduction of emitters for sdk clients.
lirenhe Jan 20, 2025
bb53d7d
add python emitter doc
msyyc Jan 21, 2025
ff9fc0d
java part
weidongxu-microsoft Jan 24, 2025
c7622ce
Merge branch 'main' into introduction-sdk-client-emitters
markcowl Jan 24, 2025
b780da9
Update the JavaScript emitter information
MaryGao Jan 24, 2025
b55dcce
refactor the content
lirenhe Jan 26, 2025
ff3a26e
add doc on Java emitter required depencencies
weidongxu-microsoft Jan 26, 2025
9ba0e86
Add note for Python client emitter.
msyyc Jan 26, 2025
f2c4dfe
Merge branch 'main' into introduction-sdk-client-emitters
lirenhe Jan 26, 2025
469c96a
Update the content of introduction.md
lirenhe Jan 26, 2025
d77ab16
Merge branch 'main' into introduction-sdk-client-emitters
lirenhe Feb 5, 2025
47db420
Merge branch 'main' into introduction-sdk-client-emitters
lirenhe Feb 8, 2025
625ddb4
Update the content based on the feedback.
lirenhe Feb 8, 2025
15d942a
Merge branch 'main' into introduction-sdk-client-emitters
lirenhe Feb 8, 2025
199426f
fix a type for display icon
lirenhe Feb 8, 2025
1f7a7a2
Update the format
lirenhe Feb 8, 2025
da71388
fix build error
lirenhe Feb 8, 2025
56992b1
Remove steps which would cause the build error.
lirenhe Feb 10, 2025
021de38
Update the sidebar
lirenhe Feb 10, 2025
0664619
Merge branch 'main' into introduction-sdk-client-emitters
lirenhe Feb 10, 2025
cd1db4d
Fix format issue.
lirenhe Feb 10, 2025
a431a92
Merge branch 'introduction-sdk-client-emitters' of https://github.com…
lirenhe Feb 10, 2025
bda5d43
Update the reference content
lirenhe Feb 10, 2025
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
102 changes: 102 additions & 0 deletions website/src/content/docs/docs/emitters/sdk-clients/introduction.md
lirenhe marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
title: introduction of SDK client emitters
---

## How to Use Client Emitters to Generate SDK from TypeSpec

### Introduction

This guide will walk you through the process of using different client emitters (JavaScript, Python, Java, .NET) to generate SDKs 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 and configure client emitters.
2. Update the client emitter configurations in `package.json` and `tspconfig.yaml`.
3. How to run the SDK generation for each specific programming language.

## Location of All Client Emitters and Common Configurations

The client emitters and their common configurations are located in the `package.json` file within your project.
lirenhe marked this conversation as resolved.
Show resolved Hide resolved

| **Emitter Name** | **Language** | **Version** | **Common Configuration** |
| ---------------------------- | ------------ | ------------------------ | ------------------------ |
| @azure-tools/typespec-ts | JavaScript | `0.37.0` | `emitter-output-dir` |
| @typespec/http-client-python | Python | `0.6.0` | `emitter-output-dir` |
| @typespec/http-client-java | Java | `0.1.6` | `emitter-output-dir` |
lirenhe marked this conversation as resolved.
Show resolved Hide resolved
| @typespec/http-client-csharp | .NET | `0.1.9-alpha.20250113.2` | `emitter-output-dir` |

### Common Configuration Options

- `emitter-output-dir`: Defines where the generated SDK files will be stored.

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-server-javascript": "^0.58.0-alpha.6",
"@typespec/http-client-java": "^0.1.6",
"@azure-tools/typespec-ts": "^0.37.0",
}
```

#### Note: Check for the Latest Version

To ensure you are using the latest version of the packages, visit npmjs.com and search for the relevant packages.

## Language-Specific Settings

### JavaScript Client Emitter

lirenhe marked this conversation as resolved.
Show resolved Hide resolved
The JavaScript SDK generator uses TypeScript language features for its emitter. You can customize the output by setting specific options in the `package.json` file.

#### Configuration Options for JavaScript

| **Configuration Name** | **Description** | **Possible Values** |
| ---------------------- | --------------- | ------------------- |
| `isModularLibrary` | | `true`, `false` |
| `azureSdkForJs` | | `true`, `false` |
| `packageDetails` | | `true`, `false` |

Example configuration:

#### Configuration Options for Python

#### Configuration Options for Java

#### Configuration Options for .NET

## Running Language-Specific Emitters in CLI

1. Ensure that your package.json file is correctly configured to include the necessary dependencies for running the emitters
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can use starlight steps to hav ea nicely presented stepped tutorial https://starlight.astro.build/components/steps/

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The required format in Steps would conflict with prettier check result which requires no space before code block.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it works fine but you have to double indent the content(then format, not sure what is the exact rule but it works), this this pr for example https://github.com/microsoft/typespec/pull/5907/files#diff-a8e95e435a79ecab53d5b97dcf924fa2e247d0d7ba63a2e27e8062731d3b1e30


1. Update the tspconfig.yaml file for properly configured for the language-specific emitter.

```yaml
emit:
- "@typespec/http-client-csharp"
- "@typespec/http-client-java"
options:
"@typespec/http-client-csharp":
emitter-output-dir: "{project-root}/../clients/dotnet"
lirenhe marked this conversation as resolved.
Show resolved Hide resolved
"@typespec/http-client-java":
emitter-output-dir: "{project-root}/../clients/java"
```

1. Once the package.json and tspconfig.yaml files are updated, you need to install all required dependencies.
lirenhe marked this conversation as resolved.
Show resolved Hide resolved

Run the following command:

```bash
tsp install
```

1. 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 .
lirenhe marked this conversation as resolved.
Show resolved Hide resolved
```

## Disclaimer

> **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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we link to the official documentation?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would be good that we include it right there on the website as well(in the same way we have docs for the other emitters)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I plan to use the readme page of each emitter,e.g.
https://www.npmjs.com/package/@typespec/http-client-csharp
However, those pages seem to be out of date which requires SDK codeGen owner to improve.

lirenhe marked this conversation as resolved.
Show resolved Hide resolved
Loading