docs: bump typedoc to 0.26.4 #9727

0xpatrickdev · 2024-07-17T21:28:45Z

closes: #9681
refs: #9729

Description

Updates typedoc to latest version
Adds script to rewrite /functions path to /funcs to avoid 🐛 BUG: Static page with a category named 'functions' (public/functions/index.html) gets discarded cloudflare/workers-sdk#2240
- includes renaming files, anchor links in html files, and a base64 encoded navigation state object in a js file

Security Considerations

n/a

Scaling Considerations

n/a

Documentation Considerations

n/a

Testing Considerations

CI and manual QA

Upgrade Considerations

n/a

cloudflare-workers-and-pages · 2024-07-17T21:29:40Z

Deploying agoric-sdk with Cloudflare Pages

Latest commit:	`4037399`
Status:	✅ Deploy successful!
Preview URL:	https://20c3c06a.agoric-sdk.pages.dev
Branch Preview URL:	https://pc-bump-typedoc.agoric-sdk.pages.dev

View logs

dckc · 2024-07-17T21:33:50Z

no joy: I get a blank page for assertAssetKind

console shows:

Refused to apply style from 'https://pc-bump-typedoc.agoric-sdk.pages.dev/functions/assets/style.css' because its MIME type ('text/html') is not a supported stylesheet MIME type, and strict MIME checking is enabled.

0xpatrickdev · 2024-07-17T22:09:44Z

no joy: I get a blank page for assertAssetKind

console shows:

Refused to apply style from 'https://pc-bump-typedoc.agoric-sdk.pages.dev/functions/assets/style.css' because its MIME type ('text/html') is not a supported stylesheet MIME type, and strict MIME checking is enabled.

Let's see if 380d57d does anything. If not, seems we should look into the CDN config

... and strict MIME checking is enabled

No luck, removed. Here was the diff

diff --git a/docs/_headers b/docs/_headers
new file mode 100644
index 0000000000..9b87c50354
--- /dev/null
+++ b/docs/_headers
@@ -0,0 +1,6 @@
+/*.css
+  Content-Type: text/css
+/*.js
+  Content-Type: text/javascript
+/*.html
+  Content-Type: text/html
diff --git a/package.json b/package.json
index 271c1eac51..f04ba33721 100644
--- a/package.json
+++ b/package.json
@@ -48,7 +48,7 @@
   "scripts": {
     "clean": "yarn lerna run --no-bail clean",
     "check-dependencies": "node ./scripts/check-mismatched-dependencies.cjs",
-    "docs": "typedoc --tsconfig tsconfig.build.json",
+    "docs": "typedoc --tsconfig tsconfig.build.json && cp docs/_headers api-docs/_headers",
     "docs:markdown-for-agoric-documentation-repo": "typedoc --plugin typedoc-plugin-markdown --tsconfig tsconfig.build.json",
     "lerna": "lerna",
     "link-cli": "yarn run create-agoric-cli",

0xpatrickdev · 2024-07-17T23:48:20Z

no joy: I get a blank page for assertAssetKind

console shows:

Refused to apply style from 'https://pc-bump-typedoc.agoric-sdk.pages.dev/functions/assets/style.css' because its MIME type ('text/html') is not a supported stylesheet MIME type, and strict MIME checking is enabled.

This seems to be the culprit: cloudflare/workers-sdk#2240. Updated the PR description to remove the fix for /functions*, we'll tackle that in a separate (forthcoming) ticket.

LuqiPan

🚢

Thank you for looking into this and getting it upgraded

0xpatrickdev · 2024-07-18T01:55:03Z

Now try /funcs instead of /functions: https://pc-bump-typedoc.agoric-sdk.pages.dev/funcs/_agoric_ertp.assertAssetKind

Decided to go for the other bug in this PR

dckc · 2024-07-18T02:52:02Z

scripts/update-typedoc-functions-path.cjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node


did you write this whole script today?

why .cjs rather than .mjs?

Yes - I paired with an LLM to to help arrive at the solution more quickly. This sort of task seemed like the perfect candidate.

And I instinctively went for .cjs as this is a build script. Will note for the future .mjs works and is preferred!

I'm skeptical of the amount of code here to work around the CF bug. Did TypeStrong/typedoc#2111 (comment) not work?

TypeStrong/typedoc#2111 (comment) is more work but looks soild.

I will approve this because it fixes the immediate problem:
https://agoric-sdk.pages.dev/funcs/_agoric_orchestration.buildRootObject
https://pc-bump-typedoc.agoric-sdk.pages.dev/funcs/_agoric_orchestration.buildRootObject

but please file an issue to come back and remove this file. I'd suggest to just merge this now but it's going to need a rebase anyway so please include in a doc comment why this file is needed, what alternatives were researched and what are possible next steps

Did TypeStrong/typedoc#2111 (comment) not work

It does not since we have JS enabled. Part of the script reaches into a build-generated base64 string in a js file that contains navigation state to also update the urls there.

TypeStrong/typedoc#2111 (comment) is more work but looks soild

I didn't try this one - the git links are dead and it seems like PlayForm/Build might do something different now - I don't see any mentions of a typedoc theme in the README. This also involves an extra dependency.

but please file an issue to come back and remove this file. I'd suggest to just merge this now but it's going to need a rebase anyway so please include in a doc comment why this file is needed, what alternatives were researched and what are possible next steps

We can leave #9729 open for this - i've updated to refs. PTAL at 092acb7 for an updated file description

turadg · 2024-07-30T15:36:34Z

package.json

    "docs:markdown-for-agoric-documentation-repo": "typedoc --plugin typedoc-plugin-markdown --tsconfig tsconfig.build.json",
+    "docs:update-functions-path": "node ./scripts/update-typedoc-functions-path.cjs",


confirming update-functions-path isn't needed for markdown-for-agoric-documentation-repo

I'm not certain here - are we currently using docs:markdown-for-agoric-documentation-repo? If yes, it seems this should be updated.

See c536276

See c536276

That was naive - I forgot automated testing in this repo doesn't cover this path. Please also see 5cf3e0f which adds required changes to process markdown files.

I tested manually. Unsure if there's a path for testing in agoric/documentation before merging.

turadg · 2024-07-30T15:42:21Z

scripts/update-typedoc-functions-path.cjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node


I'm skeptical of the amount of code here to work around the CF bug. Did TypeStrong/typedoc#2111 (comment) not work?

TypeStrong/typedoc#2111 (comment) is more work but looks soild.

I will approve this because it fixes the immediate problem:
https://agoric-sdk.pages.dev/funcs/_agoric_orchestration.buildRootObject
https://pc-bump-typedoc.agoric-sdk.pages.dev/funcs/_agoric_orchestration.buildRootObject

but please file an issue to come back and remove this file. I'd suggest to just merge this now but it's going to need a rebase anyway so please include in a doc comment why this file is needed, what alternatives were researched and what are possible next steps

turadg · 2024-07-31T13:07:45Z

scripts/update-typedoc-functions-path.cjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node


LuqiPan · 2024-08-06T16:43:47Z

We were talking about dropping our compatibility date on CF to get it working, my test plan is:

drop compatibility date on CF for preview builds
push a commit that removes docs:update-functions-path in docs script in package.json
check if we can see functions with the new build

LuqiPan · 2024-08-08T16:10:37Z

We were talking about dropping our compatibility date on CF to get it working, my test plan is:
drop compatibility date on CF for preview builds
push a commit that removes docs:update-functions-path in docs script in package.json
check if we can see functions with the new build

No dice 😢

I dropped compatibility date on both CF for preview builds and in the commit via wrangler.toml

Then I pushed a commit that removes docs:update-functions-path in docs script in package.json

However, the functions are still not showing: https://d52c115a.agoric-sdk.pages.dev/funcs/_agoric_ertp.assertAssetKind

- with 0.26, typedoc seems to have better support for Functions. currently, web pages crash when these are loaded

- avoids limitation in cloudflare pages, where we cannot publish html files to a top-level functions directory

0xpatrickdev force-pushed the pc/bump-typedoc branch 3 times, most recently from 9835a8d to 65bd8d1 Compare July 17, 2024 23:44

LuqiPan previously approved these changes Jul 17, 2024

View reviewed changes

0xpatrickdev mentioned this pull request Jul 18, 2024

typedoc function pages are not loading on agoric-sdk.pages.dev #9729

Open

0xpatrickdev force-pushed the pc/bump-typedoc branch 2 times, most recently from 38c9422 to bf1c348 Compare July 18, 2024 01:54

dckc reviewed Jul 18, 2024

View reviewed changes

LuqiPan mentioned this pull request Jul 18, 2024

chore: update typedoc to 0.26.4 #9695

Closed

turadg approved these changes Jul 30, 2024

View reviewed changes

0xpatrickdev force-pushed the pc/bump-typedoc branch from bf1c348 to c536276 Compare July 30, 2024 16:21

0xpatrickdev requested a review from turadg July 30, 2024 16:38

turadg approved these changes Jul 30, 2024

View reviewed changes

turadg mentioned this pull request Jul 31, 2024

export withOrchestration #9808

Closed

turadg approved these changes Jul 31, 2024

View reviewed changes

scripts/update-typedoc-functions-path.cjs

@@ -0,0 +1,137 @@

#!/usr/bin/env node

Copy link

Member

turadg Jul 31, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent.

LuqiPan force-pushed the pc/bump-typedoc branch from 94dd32d to 5cf3e0f Compare August 8, 2024 16:14

docs: bump typedoc to 0.26.4

669293c

- with 0.26, typedoc seems to have better support for Functions. currently, web pages crash when these are loaded

0xpatrickdev force-pushed the pc/bump-typedoc branch from 5cf3e0f to ce9a133 Compare August 8, 2024 16:57

0xpatrickdev added automerge:rebase Automatically rebase updates, then merge and removed automerge:rebase Automatically rebase updates, then merge labels Aug 8, 2024

chore(docs): rename functions to funcs in typedoc output

4037399

- avoids limitation in cloudflare pages, where we cannot publish html files to a top-level functions directory

0xpatrickdev force-pushed the pc/bump-typedoc branch from ce9a133 to 4037399 Compare August 8, 2024 16:59

0xpatrickdev added the automerge:rebase Automatically rebase updates, then merge label Aug 8, 2024

mergify bot merged commit e8c4189 into master Aug 8, 2024
88 checks passed

mergify bot deleted the pc/bump-typedoc branch August 8, 2024 17:34

samsiegart mentioned this pull request Aug 8, 2024

Docs: Fix blank function pages Agoric/ui-kit#116

Open

LuqiPan mentioned this pull request Aug 14, 2024

Search functions on agoric-sdk.pages.dev still bring users to unresolved URLs #9894

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: bump typedoc to 0.26.4 #9727

docs: bump typedoc to 0.26.4 #9727

0xpatrickdev commented Jul 17, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Jul 17, 2024 •

edited

Loading

dckc commented Jul 17, 2024

0xpatrickdev commented Jul 17, 2024 •

edited

Loading

0xpatrickdev commented Jul 17, 2024 •

edited

Loading

LuqiPan left a comment

0xpatrickdev commented Jul 18, 2024

dckc Jul 18, 2024

0xpatrickdev Jul 30, 2024

turadg Jul 30, 2024

0xpatrickdev Jul 30, 2024

0xpatrickdev Jul 30, 2024

turadg Jul 31, 2024

turadg Jul 30, 2024

0xpatrickdev Jul 30, 2024

0xpatrickdev Jul 30, 2024

0xpatrickdev Jul 31, 2024 •

edited

Loading

turadg Jul 30, 2024

turadg Jul 31, 2024

LuqiPan commented Aug 6, 2024

LuqiPan commented Aug 8, 2024 •

edited

Loading

		"docs:markdown-for-agoric-documentation-repo": "typedoc --plugin typedoc-plugin-markdown --tsconfig tsconfig.build.json",
		"docs:update-functions-path": "node ./scripts/update-typedoc-functions-path.cjs",

docs: bump typedoc to 0.26.4 #9727

docs: bump typedoc to 0.26.4 #9727

Conversation

0xpatrickdev commented Jul 17, 2024 • edited Loading

Description

Security Considerations

Scaling Considerations

Documentation Considerations

Testing Considerations

Upgrade Considerations

cloudflare-workers-and-pages bot commented Jul 17, 2024 • edited Loading

Deploying agoric-sdk with Cloudflare Pages

dckc commented Jul 17, 2024

0xpatrickdev commented Jul 17, 2024 • edited Loading

0xpatrickdev commented Jul 17, 2024 • edited Loading

LuqiPan left a comment

Choose a reason for hiding this comment

0xpatrickdev commented Jul 18, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0xpatrickdev Jul 31, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LuqiPan commented Aug 6, 2024

LuqiPan commented Aug 8, 2024 • edited Loading

0xpatrickdev commented Jul 17, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Jul 17, 2024 •

edited

Loading

0xpatrickdev commented Jul 17, 2024 •

edited

Loading

0xpatrickdev commented Jul 17, 2024 •

edited

Loading

0xpatrickdev Jul 31, 2024 •

edited

Loading

LuqiPan commented Aug 8, 2024 •

edited

Loading