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

iankhou · 2025-04-01T18:24:32Z

Fixes #367

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

codecov-commenter · 2025-04-01T18:32:26Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 85.55%. Comparing base (d21e66e) to head (bbbedb9).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #303      +/-   ##
==========================================
+ Coverage   85.49%   85.55%   +0.06%     
==========================================
  Files         219      219              
  Lines       24103    24103              
  Branches     2585     2594       +9     
==========================================
+ Hits        20607    20622      +15     
+ Misses       3445     3428      -17     
- Partials       51       53       +2

Flag	Coverage Δ
suite.unit	`85.55% <ø> (+0.06%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

mrgrain · 2025-04-02T12:01:07Z

projenrc/api-extractor-docs-publishing.ts

+    const apiExtractorDocsTask = project.addTask('api-extractor-docs', {
+      exec: [
+        // Ensure API Extractor is installed
+        'npm install -g @microsoft/api-extractor || true',


Don't use a global install, just add it as devDep

mrgrain · 2025-04-02T12:01:37Z

projenrc/api-extractor-docs-publishing.ts

+        // Ensure API Extractor is installed
+        'npm install -g @microsoft/api-extractor || true',
+        // Run api-extractor to generate the API model
+        // Use || true to ensure the task continues even if api-extractor reports failures


This seems counter intuitive? Why continue on failure?

api-extractor will still output a file when there are certain failures. Will work on fixing the underlying issue, but I did this to temporarily unblock it.

Below that, we check whether the file was outputted instead of relying on api-extractor to reliably report an error.

mrgrain · 2025-04-02T12:03:06Z

projenrc/api-extractor-docs-publishing.ts

+        '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',
+        // Find and copy all markdown files (excluding node_modules)


I reckon we can limit this to all files in the docs directory and README.md

You will probably want all files because we might have images.

Got it, that makes sense to me. I was thinking we might have .md files in subdirectories, but if that isn't the case, then we won't need anything outside of docs and README.md. And will include all file types.

mrgrain · 2025-04-02T12:04:17Z

projenrc/api-extractor-docs-publishing.ts

+
+    const safeName = this.project.name.replace('@', '').replace('/', '-');
+
+    releaseWf.addJob(`${safeName}_release_api_extractor_docs`, {


This seems to be a replication of the S3 docs workflow. Let's refactor that code to be reusable and support both uploads

mrgrain · 2025-04-02T12:05:59Z

packages/@aws-cdk/toolkit-lib/api-extractor.json

+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "./dist/<unscopedPackageName>.api.json",
+    "projectFolderUrl": "https://github.com/aws/aws-cdk-cli"


not this?

Suggested change

"projectFolderUrl": "https://github.com/aws/aws-cdk-cli"

"projectFolderUrl": "https://github.com/aws/aws-cdk-cli/tree/main/packages/%40aws-cdk/toolkit-lib"

Will change it to this.

mrgrain

left some comments

Copilot

Copilot reviewed 4 out of 11 changed files in this pull request and generated no comments.

Files not reviewed (7)

packages/@aws-cdk/toolkit-lib/.gitattributes: Language not supported
packages/@aws-cdk/toolkit-lib/.gitignore: Language not supported
packages/@aws-cdk/toolkit-lib/.projen/deps.json: Language not supported
packages/@aws-cdk/toolkit-lib/.projen/files.json: Language not supported
packages/@aws-cdk/toolkit-lib/.projen/tasks.json: Language not supported
packages/@aws-cdk/toolkit-lib/api-extractor.json: Language not supported
packages/@aws-cdk/toolkit-lib/package.json: Language not supported

Comments suppressed due to low confidence (3)

projenrc/s3-docs-publishing.ts:100

[nitpick] Consider extracting the computed role-session-name into a constant to reduce duplication across steps and mitigate potential inconsistencies.

role-session-name: `s3-${isApiExtractor ? 'api-' : ''}docs-publishing@aws-cdk-cli`

.github/workflows/release.yml:1219

[nitpick] The S3_PATH is hardcoded for the API Extractor artifact and does not use the dynamic naming logic from S3DocsPublishing; consider aligning these values for consistency.

S3_PATH="$DOCS_STREAM/aws-cdk-toolkit-lib-api-model-v$(cat dist/version.txt).zip"

.projenrc.ts:1057

Using '|| true' after running api-extractor may suppress critical error output; verify that this handling is intentional and that errors aren’t being inadvertently masked.

'api-extractor run --diagnostics || true'

OOTO, changes addressed.

github-actions · 2025-04-14T16:52:07Z

Total lines changed 1870 is greater than 1000. Please consider breaking this PR down.

iankhou had a problem deploying to integ-approval April 1, 2025 18:24 — with GitHub Actions Failure

iankhou requested a review from rix0rrr April 1, 2025 18:24

iankhou self-assigned this Apr 1, 2025

aws-cdk-automation requested a review from a team April 1, 2025 18:24

github-actions bot added the p2 label Apr 1, 2025

aws-cdk-automation enabled auto-merge April 1, 2025 18:24

iankhou had a problem deploying to integ-approval April 1, 2025 19:47 — with GitHub Actions Failure

mrgrain reviewed Apr 2, 2025

View reviewed changes

mrgrain previously requested changes Apr 2, 2025

View reviewed changes

iankhou had a problem deploying to integ-approval April 2, 2025 14:24 — with GitHub Actions Failure

iankhou had a problem deploying to integ-approval April 2, 2025 14:26 — with GitHub Actions Failure

aws-cdk-automation temporarily deployed to integ-approval April 2, 2025 14:35 — with GitHub Actions Inactive

iankhou requested a review from mrgrain April 2, 2025 14:48

aws-cdk-automation temporarily deployed to run-tests April 2, 2025 14:57 — with GitHub Actions Inactive

iankhou had a problem deploying to integ-approval April 4, 2025 14:36 — with GitHub Actions Failure

aws-cdk-automation had a problem deploying to integ-approval April 4, 2025 14:42 — with GitHub Actions Failure

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

bbbedb9

iankhou force-pushed the iankhou-api-extractor branch from bacdfda to bbbedb9 Compare April 6, 2025 17:49

iankhou temporarily deployed to integ-approval April 6, 2025 17:49 — with GitHub Actions Inactive

iankhou requested review from Copilot and removed request for mrgrain April 6, 2025 17:51

Copilot AI reviewed Apr 6, 2025

View reviewed changes

iankhou requested review from a team and removed request for a team April 6, 2025 17:52

iankhou had a problem deploying to run-tests April 6, 2025 18:01 — with GitHub Actions Failure

iankhou temporarily deployed to run-tests April 6, 2025 18:01 — with GitHub Actions Inactive

iankhou added the pr/exempt-integ-test Skips the integ test steps if set. label Apr 6, 2025

iankhou had a problem deploying to run-tests April 6, 2025 18:28 — with GitHub Actions Failure

iankhou temporarily deployed to run-tests April 6, 2025 18:52 — with GitHub Actions Inactive

iankhou removed the pr/exempt-integ-test Skips the integ test steps if set. label Apr 6, 2025

rix0rrr approved these changes Apr 7, 2025

View reviewed changes

aws-cdk-automation added this pull request to the merge queue Apr 7, 2025

Merged via the queue into main with commit 4771ed8 Apr 7, 2025
25 checks passed

aws-cdk-automation deleted the iankhou-api-extractor branch April 7, 2025 14:23

github-actions bot added the feature-request label Apr 14, 2025


		const safeName = this.project.name.replace('@', '').replace('/', '-');

		releaseWf.addJob(`${safeName}_release_api_extractor_docs`, {

	"projectFolderUrl": "https://github.com/aws/aws-cdk-cli"
	"projectFolderUrl": "https://github.com/aws/aws-cdk-cli/tree/main/packages/%40aws-cdk/toolkit-lib"

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

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

Uh oh!

Conversation

iankhou commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iankhou Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrgrain left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Apr 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

iankhou commented Apr 1, 2025 •

edited

Loading

codecov-commenter commented Apr 1, 2025 •

edited

Loading

iankhou Apr 2, 2025 •

edited

Loading