diff --git a/.chronus/changes/doc-generation-subdir-examples-2026-6-30-0-0-0.md b/.chronus/changes/doc-generation-subdir-examples-2026-6-30-0-0-0.md new file mode 100644 index 00000000000..61a9de834db --- /dev/null +++ b/.chronus/changes/doc-generation-subdir-examples-2026-6-30-0-0-0.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-python" +--- + +Add usage examples for the `generation-subdir` emitter option in the docs. diff --git a/packages/http-client-python/CONTRIBUTING.md b/packages/http-client-python/CONTRIBUTING.md index 0485707747d..7ee4d6ed7ed 100644 --- a/packages/http-client-python/CONTRIBUTING.md +++ b/packages/http-client-python/CONTRIBUTING.md @@ -15,7 +15,7 @@ Welcome! This guide will help you set up your development environment and contri Before you begin, ensure you have the following installed: -- [Node.js](https://nodejs.org/) (version 18 or higher) +- [Node.js](https://nodejs.org/) (version 22 or higher) - [npm](https://www.npmjs.com/) (comes with Node.js) - [pnpm](https://pnpm.io/) (for workspace management) - [Git](https://git-scm.com/) @@ -85,6 +85,24 @@ npm run ci - Run linting: `npm run lint` - Format code: `npm run format` +### Updating Emitter Option Documentation + +The emitter options documentation is **auto-generated** — do not edit it by hand. + +- The single source of truth is the option definitions in [`emitter/src/lib.ts`](./emitter/src/lib.ts). Update the `description` (and other schema fields) there. +- Running `npm run regen-docs` regenerates **both** targets from that source: + - This package's [`README.md`](./README.md) (the `Emitter options` section). + - The website reference docs under `website/src/content/docs/docs/emitters/clients/http-client-python/reference/`. + +Because `regen-docs` reads the **compiled** emitter, always build first: + +```bash +npm run build +npm run regen-docs +``` + +If you edit `lib.ts` but skip `npm run build`, `regen-docs` will regenerate from the stale `dist/` output and your changes won't appear. + ## Creating Pull Requests ### 1. Prepare Your PR @@ -95,7 +113,7 @@ Before creating a pull request: - [ ] Ensure code is properly formatted: `npm run format` - [ ] Ensure code is properly linted: `npm run lint` - [ ] Add a changeset: `pnpm change add` (from repo root) -- [ ] Update documentation if needed +- [ ] Update documentation if needed (if you changed emitter options in `lib.ts`, run `npm run build && npm run regen-docs` — see [Updating Emitter Option Documentation](#updating-emitter-option-documentation)) ### 2. Create the PR @@ -119,45 +137,19 @@ Both must pass before your PR can be merged. ### Manual Regeneration Testing -You can manually trigger the [TypeSpec Python Regenerate Tests](https://github.com/Azure/azure-sdk-for-python/actions/workflows/typespec-python-regenerate.yml) workflow in `azure-sdk-for-python` to regenerate tests with either emitter: - -- **Branded** (`@azure-tools/typespec-python`): Select "branded" and optionally specify a version. If no version is given, it uses the version from [`eng/emitter-package.json`](https://github.com/Azure/azure-sdk-for-python/blob/main/eng/emitter-package.json). -- **Unbranded** (`@typespec/http-client-python`): Select "unbranded" and optionally specify a version. If no version is given, it uses the latest published version on npm. - -The workflow checks out `microsoft/typespec` (at the ref you specify, defaulting to `main`), builds the regeneration infrastructure, installs the target emitter from npm, and runs the full regeneration. +You can manually trigger the [TypeSpec Python Regenerate Tests](https://github.com/Azure/azure-sdk-for-python/actions/workflows/typespec-python-regenerate.yml) workflow in `azure-sdk-for-python` to regenerate tests. The workflow checks out `microsoft/typespec` (at the ref you specify, defaulting to `main`), builds the regeneration infrastructure, installs the target emitter from npm, and runs the full regeneration. ### Post-Release: Updating azure-sdk-for-python -Once a new version of the branded emitter (`@azure-tools/typespec-python`) is released, follow these steps to update `azure-sdk-for-python`: +Once a new version of this emitter is released, follow these steps to update `azure-sdk-for-python`: -1. **Update `eng/emitter-package.json`** in [Azure/azure-sdk-for-python](https://github.com/Azure/azure-sdk-for-python): +1. Follow skill [emitter-package-update](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/skills/emitter-package-update) to **create a PR** to update `eng/emitter-package.json` and `eng/emitter-package-lock.json` and submit them to `azure-sdk-for-python`. - Update the `@azure-tools/typespec-python` version to the newly released version: +2. **Automatic regeneration**: Once the PR merges to `main`, the [TypeSpec Python Regenerate Tests](https://github.com/Azure/azure-sdk-for-python/actions/workflows/typespec-python-regenerate.yml) workflow triggers automatically (it watches for changes to `eng/emitter-package.json`). It regenerates all test code and creates a follow-up issue with the updated generated files. - ```json - { - "dependencies": { - "@azure-tools/typespec-python": "" - } - } - ``` - -2. **Regenerate config files** using `tsp-client`: - - ```bash - tsp-client generate-config-files \ - --package-json= < path-to-local-typespec-azure > /packages/typespec-python/package.json - ``` - - This updates the `devDependencies` in `eng/emitter-package.json` to match the branded emitter's peer dependencies. - -3. **Create a PR** with the updated `eng/emitter-package.json` and submit it to `azure-sdk-for-python`. - -4. **Automatic regeneration**: Once the PR merges to `main`, the [TypeSpec Python Regenerate Tests](https://github.com/Azure/azure-sdk-for-python/actions/workflows/typespec-python-regenerate.yml) workflow triggers automatically (it watches for changes to `eng/emitter-package.json`). It regenerates all test code and creates a follow-up PR with the updated generated files. - -5. **Generated code location**: The regenerated tests are checked in at [`eng/tools/azure-sdk-tools/emitter/generated/`](https://github.com/Azure/azure-sdk-for-python/tree/main/eng/tools/azure-sdk-tools/emitter/generated) in `azure-sdk-for-python`, split into: - - `azure/` — Tests generated with the branded emitter (Azure SDK specs) - - `unbranded/` — Tests generated with the unbranded emitter (TypeSpec HTTP specs) +3. **Generated code location**: The regenerated tests are checked in at [`eng/tools/azure-sdk-tools/emitter/generated`](https://github.com/Azure/azure-sdk-for-python/tree/typespec-python-generated-tests/eng/tools/azure-sdk-tools/emitter/generated) in `azure-sdk-for-python`, split into: + - `azure/` — Tests generated with the branded emitter (Azure HTTP specs) + - `unbranded/` — Tests generated with the unbranded emitter (HTTP specs) ## Release Process @@ -175,13 +167,15 @@ This consumes all pending change files under `.chronus/changes/` for this packag ### 2. Create a Release PR -Create a branch from the version bump commit and open a PR to `main`: +Create a branch from the version bump commit, push it, and open a PR to `main`: ```bash git checkout -b publish/python-release- git push origin publish/python-release- ``` +Then open a pull request targeting `main` (for example, via the GitHub UI or `gh pr create --base main`). + > **Note:** The branch **must** use the `publish/` prefix. This tells CI to skip certain checks (consistency, external-integration) and enables auto-publish on merge. ### 3. Merge and Publish diff --git a/packages/http-client-python/README.md b/packages/http-client-python/README.md index 4822e263c6a..980cbb66703 100644 --- a/packages/http-client-python/README.md +++ b/packages/http-client-python/README.md @@ -44,9 +44,9 @@ See [Configuring output directory for more info](https://typespec.io/docs/handbo ### `api-version` -**Type:** `string` +**Type:** `undefined` -Use this flag if you would like to generate the sdk only for a specific version. Default value is the latest version. Also accepts values `latest` and `all`. +Use this flag if you would like to generate the sdk only for a specific version. Default value is the latest version. Also accepts values `latest` and `all`. For multi-service packages, provide a map from each service namespace's full name to its desired version; services not listed default to their latest version. ### `license` @@ -112,7 +112,17 @@ Whether to validate the versioning of the package. Defaults to `true`. If set to **Type:** `string` -The subdirectory to generate the code in. If not specified, the code will be generated in the root folder. Note: if you're using this flag, you will need to add and maintain the versioning file yourself. +The subdirectory (relative to the package namespace folder) to generate the code in. Use this to keep emitter-generated code separate from hand-written/customized code, so regeneration only overwrites the subdirectory and leaves your customizations untouched. If not specified, the code is generated directly in the package namespace folder. Note: if you're using this flag, you will need to add and maintain the versioning file (`_version.py`) yourself. + +Example: for `namespace: azure.storage.blob` with `generation-subdir: _generated`, generated code lands in `azure/storage/blob/_generated/` while your customized code lives in `azure/storage/blob/`. A typical `tspconfig.yaml` looks like: + +```yaml +options: + "@azure-tools/typespec-python": + emitter-output-dir: "{output-dir}/{service-dir}/azure-storage-blob" + namespace: "azure.storage.blob" + generation-subdir: "_generated" +``` ### `keep-setup-py` @@ -120,8 +130,20 @@ The subdirectory to generate the code in. If not specified, the code will be gen Whether to keep the existing `setup.py` when `generate-packaging-files` is `true`. If set to `false` and by default, `pyproject.toml` will be generated instead. To generate `setup.py`, use `basic-setup-py`. +### `keep-pyproject-fields` + +**Type:** `object` + +Which manually customized `[project]` fields to preserve in an existing `pyproject.toml` instead of overwriting them on regeneration. Set a field to `true` to keep it. By default no fields are preserved. + ### `clear-output-folder` **Type:** `boolean` Whether to clear the output folder before generating the code. Defaults to `false`. + +### `emit-yaml-only` + +**Type:** `boolean` + +Emit YAML code model only, without running Python generator. For batch processing. diff --git a/packages/http-client-python/emitter/src/lib.ts b/packages/http-client-python/emitter/src/lib.ts index 650dff7ea48..70d5d0d081f 100644 --- a/packages/http-client-python/emitter/src/lib.ts +++ b/packages/http-client-python/emitter/src/lib.ts @@ -103,7 +103,7 @@ export const PythonEmitterOptionsSchema: JSONSchemaType = type: "string", nullable: true, description: - "The subdirectory to generate the code in. If not specified, the code will be generated in the root folder. Note: if you're using this flag, you will need to add and maintain the versioning file yourself.", + 'The subdirectory (relative to the package namespace folder) to generate the code in. Use this to keep emitter-generated code separate from hand-written/customized code, so regeneration only overwrites the subdirectory and leaves your customizations untouched. If not specified, the code is generated directly in the package namespace folder. Note: if you\'re using this flag, you will need to add and maintain the versioning file (`_version.py`) yourself.\n\nExample: for `namespace: azure.storage.blob` with `generation-subdir: _generated`, generated code lands in `azure/storage/blob/_generated/` while your customized code lives in `azure/storage/blob/`. A typical `tspconfig.yaml` looks like:\n\n```yaml\noptions:\n "@azure-tools/typespec-python":\n emitter-output-dir: "{output-dir}/{service-dir}/azure-storage-blob"\n namespace: "azure.storage.blob"\n generation-subdir: "_generated"\n```', }, "keep-setup-py": { type: "boolean", diff --git a/website/src/content/docs/docs/emitters/clients/http-client-python/reference/emitter.md b/website/src/content/docs/docs/emitters/clients/http-client-python/reference/emitter.md index 438f8ae11f5..d39beaf8112 100644 --- a/website/src/content/docs/docs/emitters/clients/http-client-python/reference/emitter.md +++ b/website/src/content/docs/docs/emitters/clients/http-client-python/reference/emitter.md @@ -38,9 +38,9 @@ See [Configuring output directory for more info](https://typespec.io/docs/handbo ### `api-version` -**Type:** `string` +**Type:** `undefined` -Use this flag if you would like to generate the sdk only for a specific version. Default value is the latest version. Also accepts values `latest` and `all`. +Use this flag if you would like to generate the sdk only for a specific version. Default value is the latest version. Also accepts values `latest` and `all`. For multi-service packages, provide a map from each service namespace's full name to its desired version; services not listed default to their latest version. ### `license` @@ -106,7 +106,17 @@ Whether to validate the versioning of the package. Defaults to `true`. If set to **Type:** `string` -The subdirectory to generate the code in. If not specified, the code will be generated in the root folder. Note: if you're using this flag, you will need to add and maintain the versioning file yourself. +The subdirectory (relative to the package namespace folder) to generate the code in. Use this to keep emitter-generated code separate from hand-written/customized code, so regeneration only overwrites the subdirectory and leaves your customizations untouched. If not specified, the code is generated directly in the package namespace folder. Note: if you're using this flag, you will need to add and maintain the versioning file (`_version.py`) yourself. + +Example: for `namespace: azure.storage.blob` with `generation-subdir: _generated`, generated code lands in `azure/storage/blob/_generated/` while your customized code lives in `azure/storage/blob/`. A typical `tspconfig.yaml` looks like: + +```yaml +options: + "@azure-tools/typespec-python": + emitter-output-dir: "{output-dir}/{service-dir}/azure-storage-blob" + namespace: "azure.storage.blob" + generation-subdir: "_generated" +``` ### `keep-setup-py` @@ -118,10 +128,16 @@ Whether to keep the existing `setup.py` when `generate-packaging-files` is `true **Type:** `object` -Which manually customized `[project]` fields to preserve in an existing `pyproject.toml` instead of overwriting them on regeneration. Set a field to `true` to keep it. Supported fields: `authors`, `description`, `classifiers`, `urls`. By default no fields are preserved. +Which manually customized `[project]` fields to preserve in an existing `pyproject.toml` instead of overwriting them on regeneration. Set a field to `true` to keep it. By default no fields are preserved. ### `clear-output-folder` **Type:** `boolean` Whether to clear the output folder before generating the code. Defaults to `false`. + +### `emit-yaml-only` + +**Type:** `boolean` + +Emit YAML code model only, without running Python generator. For batch processing.