Skip to content

Commit d091a68

Browse files
JosmithrJosmithr
authored
build(api-markdown-documenter): Simplify API-Extractor setup (#24800)
This package is versioned and published independently from the rest of the repo. It was previously set up to use our shared base API-Extractor configs, which are configured for packages in release groups that version/publish many packages together. Specific changes: - Don't extend shared config - Remove "lint" config (unused and unneeded) - Restore rollup generation - Fix `/beta` export path - Remove alpha report (this package has no alpha APIs nor export)
1 parent 3dc1105 commit d091a68

File tree

4 files changed

+223
-951
lines changed

4 files changed

+223
-951
lines changed

‎tools/api-markdown-documenter/api-extractor-lint.json‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎tools/api-markdown-documenter/api-extractor.json‎

Lines changed: 221 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,224 @@
11
{
22
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
3-
"extends": "../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
3+
4+
"compiler": {
5+
"tsconfigFilePath": "<projectFolder>/tsconfig.json"
6+
},
7+
8+
/**
9+
* Specifies the .d.ts file to be used as the starting point for analysis. API Extractor analyzes the symbols exported by this module.
10+
* Can be overridden as necessary for packages with different build structures.
11+
*
12+
* See: <https://api-extractor.com/pages/configs/api-extractor_json/#mainentrypointfilepath>
13+
*/
14+
"mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
15+
16+
/**
17+
* Configures how the API report file (*.api.md) will be generated.
18+
*/
19+
"apiReport": {
20+
"enabled": true,
21+
"reportFileName": "<unscopedPackageName>",
22+
"reportFolder": "<projectFolder>/api-report/",
23+
"reportTempFolder": "<projectFolder>/_api-extractor-temp/",
24+
"reportVariants": ["public", "beta"]
25+
},
26+
27+
/**
28+
* Configures how the doc model file (*.api.json) will be generated.
29+
*/
30+
"docModel": {
31+
"enabled": true,
32+
"apiJsonFilePath": "<projectFolder>/_api-extractor-temp/doc-models/<unscopedPackageName>.api.json"
33+
},
34+
35+
/**
36+
* Configures how the .d.ts rollup file will be generated.
37+
*/
38+
"dtsRollup": {
39+
"enabled": true,
40+
"untrimmedFilePath": "<projectFolder>/lib/<unscopedPackageName>.d.ts",
41+
"betaTrimmedFilePath": "<projectFolder>/lib/<unscopedPackageName>-beta.d.ts"
42+
},
43+
44+
/**
45+
* Configures how the tsdoc-metadata.json file will be generated.
46+
*/
47+
"tsdocMetadata": {
48+
"enabled": true,
49+
"tsdocMetadataFilePath": "<projectFolder>/lib/tsdoc-metadata.json"
50+
},
51+
52+
/**
53+
* Configures how API Extractor reports error and warning messages produced during analysis.
54+
*
55+
* There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
56+
*/
57+
"messages": {
58+
/**
59+
* Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
60+
* the input .d.ts files.
61+
*
62+
* TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
63+
*
64+
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
65+
*/
66+
"compilerMessageReporting": {
67+
/**
68+
* Configures the default routing for messages that don't match an explicit rule in this table.
69+
*/
70+
"default": {
71+
/**
72+
* Specifies whether the message should be written to the tool's output log. Note that
73+
* the "addToApiReviewFile" property may supersede this option.
74+
*
75+
* Possible values: "error", "warning", "none"
76+
*
77+
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
78+
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
79+
* the "--local" option), the warning is displayed but the build will not fail.
80+
*/
81+
"logLevel": "error",
82+
83+
/**
84+
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
85+
* then the message will be written inside that file; otherwise, the message is instead logged according to
86+
* the "logLevel" option.
87+
*/
88+
"addToApiReportFile": false // Ensure build failure on errors
89+
}
90+
},
91+
92+
/**
93+
* Configures handling of messages reported by API Extractor during its analysis.
94+
*
95+
* API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
96+
*
97+
* DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
98+
*/
99+
"extractorMessageReporting": {
100+
"default": {
101+
/**
102+
* Specifies whether the message should be written to the the tool's output log. Note that
103+
* the "addToApiReviewFile" property may supersede this option.
104+
*
105+
* Possible values: "error", "warning", "none"
106+
*
107+
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
108+
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
109+
* the "--local" option), the warning is displayed but the build will not fail.
110+
*/
111+
"logLevel": "error",
112+
113+
/**
114+
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
115+
* then the message will be written inside that file; otherwise, the message is instead logged according to
116+
* the "logLevel" option.
117+
*/
118+
"addToApiReportFile": false // Ensure build failure on errors
119+
},
120+
121+
// #region Enabled Rules
122+
123+
// Prevent cyclic `@inheritDoc` comments
124+
"ae-cyclic-inherit-doc": {
125+
"logLevel": "error",
126+
"addToApiReportFile": false
127+
},
128+
// A documentation comment should contain at most one release tag.
129+
"ae-extra-release-tag": {
130+
"logLevel": "error",
131+
"addToApiReportFile": false
132+
},
133+
// Reported when an exported API refers to another declaration that is not exported.
134+
"ae-forgotten-export": {
135+
"logLevel": "error",
136+
"addToApiReportFile": false
137+
},
138+
// A type signature should not reference another types whose release tag is less visible.
139+
"ae-incompatible-release-tags": {
140+
"logLevel": "error",
141+
"addToApiReportFile": false
142+
},
143+
// Multiple function overloads should not have @internal tags with other tags.
144+
"ae-internal-mixed-release-tag": {
145+
"logLevel": "error",
146+
"addToApiReportFile": false
147+
},
148+
// Require packages to include `@packageDocumentation` comment
149+
"ae-misplaced-package-tag": {
150+
"logLevel": "error",
151+
"addToApiReportFile": false
152+
},
153+
// Require explicit release tags for all API members.
154+
"ae-missing-release-tag": {
155+
"logLevel": "error",
156+
"addToApiReportFile": false
157+
},
158+
159+
// Require documentation on all package-exported API items.
160+
"ae-undocumented": {
161+
// TODO: fix violations and re-enable this rule
162+
"logLevel": "none"
163+
},
164+
165+
// The @inheritDoc tag needs a TSDoc declaration reference.
166+
"ae-unresolved-inheritdoc-base": {
167+
"logLevel": "error",
168+
"addToApiReportFile": false
169+
},
170+
"ae-unresolved-inheritdoc-reference": {
171+
"logLevel": "error",
172+
"addToApiReportFile": false
173+
},
174+
175+
// The @link tag needs a TSDoc declaration reference.
176+
"ae-unresolved-link": {
177+
"logLevel": "error",
178+
"addToApiReportFile": false
179+
},
180+
181+
// #endregion
182+
183+
// #region Disabled Rules
184+
185+
// Disabled. We don't require that internal members be prefixed with an underscore.
186+
"ae-internal-missing-underscore": {
187+
"logLevel": "none",
188+
"addToApiReportFile": false
189+
}
190+
191+
// #endregion
192+
},
193+
194+
/**
195+
* Configures handling of messages reported by the TSDoc parser when analyzing code comments.
196+
*
197+
* TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
198+
*
199+
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
200+
*/
201+
"tsdocMessageReporting": {
202+
"default": {
203+
/**
204+
* Specifies whether the message should be written to the the tool's output log. Note that
205+
* the "addToApiReviewFile" property may supersede this option.
206+
*
207+
* Possible values: "error", "warning", "none"
208+
*
209+
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
210+
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
211+
* the "--local" option), the warning is displayed but the build will not fail.
212+
*/
213+
"logLevel": "error",
214+
215+
/**
216+
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
217+
* then the message will be written inside that file; otherwise, the message is instead logged according to
218+
* the "logLevel" option.
219+
*/
220+
"addToApiReportFile": false // Ensure build failure on errors
221+
}
222+
}
223+
}
4224
}

0 commit comments

Comments
 (0)