From f1bb4e6556cff77bf1528b7681c4f22048ca28cd Mon Sep 17 00:00:00 2001 From: Momo Kornher Date: Mon, 20 May 2024 14:22:28 +0100 Subject: [PATCH] chore: small fixes to docs for user-provided tsconfig (#4518) --- By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license]. [Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0 --- .../lib-author/configuration/index.md | 28 +++++++++++-------- gh-pages/partials/tsconfig-rulesets.md | 16 +++++------ 2 files changed, 24 insertions(+), 20 deletions(-) diff --git a/gh-pages/content/user-guides/lib-author/configuration/index.md b/gh-pages/content/user-guides/lib-author/configuration/index.md index bc4333b8c3..f72a12d361 100644 --- a/gh-pages/content/user-guides/lib-author/configuration/index.md +++ b/gh-pages/content/user-guides/lib-author/configuration/index.md @@ -135,16 +135,16 @@ package maintainer, the generic interpretation for those on packages is: In order to configure the behavior of `jsii`, the `package.json` file must include a `jsii` section that can contain the following entries: -| Field | Type | Required | Default | Supported versions | -| ------------------- | ---------------------------------------------- | :-----------------------------: | ------------------------------------ | ------------------ | -| `excludeTypescript` | `#!ts string[]` | | _none_ | _all_ | -| `metadata` | `#!ts object` | | _none_ | _all_ | -| `projectReferences` | `#!ts boolean` | | `#!ts true` | _all_ | -| `targets` | `#!ts object` | :octicons-check-circle-fill-24: | | _all_ | -| `tsc` | `#!ts object` | | `#!ts { outDir: '.', rootDir: '.' }` | _all_ | -| `tsconfig` | `#!ts string` | | _none_ | `>= 5.2` | -| `validateTsconfig` | `#!ts 'strict'\|'generated'\|'minimal'\|'off'` | | _none_ | `>= 5.2` | -| `versionFormat` | `#!ts 'short'\|'full'` | | `#!ts 'full'` | _all_ | +| Field | Type | Required | Default | Supported versions | +| ------------------- | ------------------------------------------------- | :-----------------------------: | ------------------------------------ | ------------------ | +| `excludeTypescript` | `#!ts string[]` | | _none_ | _all_ | +| `metadata` | `#!ts object` | | _none_ | _all_ | +| `projectReferences` | `#!ts boolean` | | `#!ts true` | _all_ | +| `targets` | `#!ts object` | :octicons-check-circle-fill-24: | | _all_ | +| `tsc` | `#!ts object` | | `#!ts { outDir: '.', rootDir: '.' }` | _all_ | +| `tsconfig` | `#!ts string` | | _none_ | `>= 5.2` | +| `validateTsconfig` | `#!ts 'strict' | 'generated' | 'minimal' | 'off'` | | _none_ | `>= 5.2` | +| `versionFormat` | `#!ts 'short' | 'full'` | | `#!ts 'full'` | _all_ | ### Language targets @@ -216,7 +216,9 @@ Refer to the [TypeScript compiler options reference][ts-options] for more inform [`tsconfig.json`]: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html [ts-options]: https://www.typescriptlang.org/docs/handbook/compiler-options.html -#### `tsconfig` _(available from jsii >= 5.2)_ +#### `tsconfig` + +_Available from jsii >= 5.2_ !!! warn :test_tube: This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified @@ -234,7 +236,9 @@ The provided tsconfig is subject to validation rules, see below for more details } ``` -#### :test_tube: `validateTsconfig` _(available from jsii >= 5.2)_ +#### `validateTsconfig` + +_Available from jsii >= 5.2_ !!! warn :test_tube: This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified diff --git a/gh-pages/partials/tsconfig-rulesets.md b/gh-pages/partials/tsconfig-rulesets.md index b184b5c6ae..3acfb88679 100644 --- a/gh-pages/partials/tsconfig-rulesets.md +++ b/gh-pages/partials/tsconfig-rulesets.md @@ -1,11 +1,11 @@ -| Rule set | Description | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `strict` :star: | (Default) Validates the provided config against a strict rule set designed for widespread support and backwards-compatibility. | -| `generated` | Enforces a tsconfig as if it were generated by jsii. Use this to stay compatible with the generated config, but have full ownership over the file. | -| `minimal` :warn: | Only reject options that are known to be incompatible with jsii. This rule set is likely to be incomplete and new rules will be added without notice as incompatibilities are discovered. | -| `off` :warn: | Disables all config validation, including options that are known to be incompatible with jsii. Intended for experimentation only. Use at your own risk. | +| Rule set | Description | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `strict` :star: | (Default) Validates the provided config against a strict rule set designed for widespread support and backwards-compatibility. | +| `generated` | Enforces a tsconfig as if it were generated by jsii. Use this to stay compatible with the generated config, but have full ownership over the file. | +| `minimal` :warning: | Only reject options that are known to be incompatible with jsii. This rule set is likely to be incomplete and new rules will be added without notice as incompatibilities are discovered. | +| `off` :warning: | Disables all config validation, including options that are known to be incompatible with jsii. Intended for experimentation only. Use at your own risk. | -:star: Recommended setting -:warn: Resulting jsii assembly/package may be incompatible with wider ecosystem +:star: Recommended setting\ +:warning: Resulting jsii assembly/package may be incompatible with wider ecosystem There is currently no easy way to inspect these rule sets, however detailed error messages are returned if a provided tsconfig fails validation.