-
Notifications
You must be signed in to change notification settings - Fork 238
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
base: main
Are you sure you want to change the base?
Conversation
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.
No changes needing a change description found. |
You can try these changes here
|
Need each language owner to update their language specific contents: Java: @weidongxu-microsoft |
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
Show resolved
Hide resolved
Currently Java emitter does not have important emitter options to add. We are checking if we need to have a (potentially cross-language) |
If there is no additional options to add, could you put some information like
|
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
Show resolved
Hide resolved
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
Show resolved
Hide resolved
@JoshLove-msft, could you help to update and review the content for .NET? Thanks |
|
||
No additional setting needed for Java. | ||
|
||
### .NET Client Emitter |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
Show resolved
Hide resolved
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
Show resolved
Hide resolved
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
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.
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
Show resolved
Hide resolved
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
Show resolved
Hide resolved
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
Show resolved
Hide resolved
|
||
## 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 |
There was a problem hiding this comment.
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/
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
website/src/content/docs/docs/emitters/sdk-clients/introduction.md
Outdated
Show resolved
Hide resolved
…/microsoft/typespec into introduction-sdk-client-emitters
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