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

Conversation

lirenhe
Copy link
Member

@lirenhe lirenhe commented Jan 20, 2025

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

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.
@microsoft-github-policy-service microsoft-github-policy-service bot added the meta:website TypeSpec.io updates label Jan 20, 2025
@azure-sdk
Copy link
Collaborator

No changes needing a change description found.

@azure-sdk
Copy link
Collaborator

azure-sdk commented Jan 20, 2025

You can try these changes here

🛝 Playground 🌐 Website 📚 Next docs 🛝 VSCode Extension

@lirenhe
Copy link
Member Author

lirenhe commented Jan 20, 2025

Need each language owner to update their language specific contents:

Java: @weidongxu-microsoft
JS: @MaryGao
Python: @msyyc
.NET: @JoshLove-msft

@weidongxu-microsoft
Copy link
Contributor

weidongxu-microsoft commented Jan 21, 2025

Currently Java emitter does not have important emitter options to add.

We are checking if we need to have a (potentially cross-language) package-name emitter option. E.g. <groupdId>:<artifactId> for Java
(for azure, the <groupId> is com.azure/com.azure.resourcemanager, and <artifactId> is from SDK namespace -- but this is no longer a valid assumption for unbranded)

@lirenhe
Copy link
Member Author

lirenhe commented Jan 21, 2025

Currently Java emitter does not have important emitter options to add.

We are checking if we need to have a (potentially cross-language) package-name emitter option. E.g. <groupdId>:<artifactId> for Java (for azure, the <groupId> is com.azure/com.azure.resourcemanager, and <artifactId> is from SDK namespace -- but this is no longer a valid assumption for unbranded)

If there is no additional options to add, could you put some information like no additional setting needed for Java under

#### Configuration Options for Java

@lirenhe lirenhe changed the title [WIP] Add the introduction of emitters for sdk clients. Add the introduction of emitters for sdk clients. Jan 26, 2025
@lirenhe
Copy link
Member Author

lirenhe commented Jan 26, 2025

@JoshLove-msft, could you help to update and review the content for .NET? Thanks


No additional setting needed for Java.

### .NET Client Emitter
Copy link
Contributor

Choose a reason for hiding this comment

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

Is the goal of this section to list the available options or to list additional required options? If no languages have any other required options, is there any reason to retain each language option section? If the goal is to list all the additional options, then there are several other options for .NET. https://github.com/microsoft/typespec/blob/main/packages/http-client-csharp/emitter/src/options.ts#L10-L26

Copy link
Member

Choose a reason for hiding this comment

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

yeah +1, not sure what the point is of this section, we shouldn't have any required option to start.

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 goal is to list the available options (required/optional)that customers could set in tspconfig.yaml for each language emitters.
I added those section as a place holder and let each SDK owner to decide what to include in this section.

@JoshLove-msft, if you think some of the options above are valuable for 3rd party customers to use, please include them there and provide the description, possible values, otherwise, you could remove this section for .NET.


## 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.


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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
meta:website TypeSpec.io updates
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create a "how to generate" for 3P scenarios
9 participants