feat(docs): api-extractor changes and gh workflow update (#303)

Uses projen to generate the api-extractor config.

Adds `api-extractor` JSON output and .md files to the S3 bucket for docs
during release.

Does not affect the existing TypeDoc site workflow.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Author: iankhou

.github/workflows/release.yml

@@ -12,7 +12,7 @@ import { JsiiBuild } from './projenrc/jsii';
 import { LargePrChecker } from './projenrc/large-pr-checker';
 import { PrLabeler } from './projenrc/pr-labeler';
 import { RecordPublishingTimestamp } from './projenrc/record-publishing-timestamp';
-import { S3DocsPublishing } from './projenrc/s3-docs-publishing';
+import { DocType, S3DocsPublishing } from './projenrc/s3-docs-publishing';
 
 // 5.7 sometimes gives a weird error in `ts-jest` in `@aws-cdk/cli-lib-alpha`
 // https://github.com/microsoft/TypeScript/issues/60159
@@ -880,6 +880,7 @@ const toolkitLib = configureProject(
       'dts-bundle-generator@9.3.1', // use this specific version because newer versions are much slower. This is a temporary arrangement we hope to remove soon anyway.
       'esbuild',
       'typedoc',
+      '@microsoft/api-extractor',
     ],
     // Watch 2 directories at once
     releasableCommits: transitiveToolkitPackages('@aws-cdk/toolkit-lib'),
@@ -914,11 +915,64 @@ const toolkitLib = configureProject(
   }),
 );
 
+// TypeDoc documentation publishing
 new S3DocsPublishing(toolkitLib, {
   docsStream: 'toolkit-lib',
   artifactPath: 'docs.zip',
   bucketName: '${{ vars.DOCS_BUCKET_NAME }}',
   roleToAssume: '${{ vars.PUBLISH_TOOLKIT_LIB_DOCS_ROLE_ARN }}',
+  docType: DocType.TYPEDOC,
+});
+
+// API Extractor documentation publishing
+new S3DocsPublishing(toolkitLib, {
+  docsStream: 'toolkit-lib',
+  artifactPath: 'api-extractor-docs.zip',
+  bucketName: '${{ vars.DOCS_BUCKET_NAME }}',
+  roleToAssume: '${{ vars.PUBLISH_TOOLKIT_LIB_DOCS_ROLE_ARN }}',
+  docType: DocType.API_EXTRACTOR,
+});
+
+// Add API Extractor configuration
+new pj.JsonFile(toolkitLib, 'api-extractor.json', {
+  marker: false,
+  obj: {
+    projectFolder: '.',
+    mainEntryPointFilePath: '<projectFolder>/lib/index.d.ts',
+    bundledPackages: [],
+    apiReport: {
+      enabled: false,
+    },
+    docModel: {
+      enabled: true,
+      apiJsonFilePath: './dist/<unscopedPackageName>.api.json',
+      projectFolderUrl: 'https://github.com/aws/aws-cdk-cli/tree/main/packages/%40aws-cdk/toolkit-lib',
+    },
+    dtsRollup: {
+      enabled: false,
+    },
+    tsdocMetadata: {
+      enabled: false,
+    },
+    messages: {
+      compilerMessageReporting: {
+        default: {
+          logLevel: 'warning',
+        },
+      },
+      extractorMessageReporting: {
+        default: {
+          logLevel: 'warning',
+        },
+      },
+      tsdocMessageReporting: {
+        default: {
+          logLevel: 'warning',
+        },
+      },
+    },
+  },
+  committed: true,
 });
 
 // Eslint rules
@@ -990,12 +1044,35 @@ toolkitLib.gitignore.addPatterns(
   '!test/_fixtures/**/cdk.out',
 );
 
-// Add a command for the docs
+// Add a command for the Typedoc docs
 const toolkitLibDocs = toolkitLib.addTask('docs', {
   exec: 'typedoc lib/index.ts',
   receiveArgs: true,
 });
 
+// Add commands for the API Extractor docs
+const apiExtractorDocsTask = toolkitLib.addTask('api-extractor-docs', {
+  exec: [
+    // Run api-extractor to generate the API model
+    'api-extractor run --diagnostics || true',
+    // Create a directory for the API model
+    'mkdir -p dist/api-extractor-docs/cdk/api/toolkit-lib',
+    // Copy the API model to the directory (with error handling)
+    'if [ -f dist/toolkit-lib.api.json ]; then cp dist/toolkit-lib.api.json dist/api-extractor-docs/cdk/api/toolkit-lib/; else echo "Warning: API JSON file not found"; fi',
+    // Add version file
+    '(cat dist/version.txt || echo "latest") > dist/api-extractor-docs/cdk/api/toolkit-lib/VERSION',
+    // Copy README.md if it exists
+    'if [ -f README.md ]; then cp README.md dist/api-extractor-docs/cdk/api/toolkit-lib/; fi',
+    // Copy all files from docs directory if it exists
+    'if [ -d docs ]; then mkdir -p dist/api-extractor-docs/cdk/api/toolkit-lib/docs && cp -r docs/* dist/api-extractor-docs/cdk/api/toolkit-lib/docs/; fi',
+    // Zip the API model and docs files
+    'cd dist/api-extractor-docs && zip -r ../api-extractor-docs.zip cdk',
+  ].join(' && '),
+});
+
+// Add the API Extractor docs task to the package task
+toolkitLib.packageTask.spawn(apiExtractorDocsTask);
+
 // When packaging, output the docs into a specific nested directory
 // This is required because the zip file needs to have this structure when created
 toolkitLib.packageTask.spawn(toolkitLibDocs, { args: ['--out dist/docs/cdk/api/toolkit-lib'] });