Timer Service updates

[dckc]

closes #948

replaces time-related reference docs with a link to https://agoric-sdk.pages.dev/modules/_agoric_time

rendered:

• https://dc-timer-ref.documentation-7tp.pages.dev/reference/repl/timerServices.html
• https://dc-timer-ref.documentation-7tp.pages.dev/guides/coreeval/permissions.html

[mergify]

⚠️ The sha of the head commit of this PR conflicts with #1022. Mergify cannot evaluate rules on this PR. ⚠️

[Chris-Hibbert]

The preview is not yet generating, but when this was part of #1022, I could see that there were gaps in the doc this is generated from. I'd like to fill in some of that. How did you build this? What do I have to do to correct the source material? Is this generated purely from types.d.ts?

[dckc]

Is this generated purely from types.d.ts?

Yes.

[mergify]

⚠️ The sha of the head commit of this PR conflicts with #1022. Mergify cannot evaluate rules on this PR. ⚠️

[mergify]

⚠️ The sha of the head commit of this PR conflicts with #1022. Mergify cannot evaluate rules on this PR. ⚠️

[cloudflare-workers-and-pages]

Deploying documentation with    Cloudflare Pages

Latest commit:	3785ca8
Status:	✅  Deploy successful!
Preview URL:	https://c512e635.documentation-7tp.pages.dev
Branch Preview URL:	https://dc-timer-ref.documentation-7tp.pages.dev

View logs

[dckc]

for reference...

... How did you build this? ...

with yarn typedoc in agoric-sdk, using a markdown plugin:

~/projects/agoric-sdk$ yarn add -W -D typedoc typedoc-plugin-markdown

diff --git a/typedoc.json b/typedoc.json
index 685abaab4..061bccfaa 100644
--- a/typedoc.json
+++ b/typedoc.json
@@ -7,6 +7,7 @@
   ],
   "name": "API documentation of Agoric SDK ",
   "entryPointStrategy": "packages",
+  "plugin": ["typedoc-plugin-markdown"],
   "out": "api-docs",
   "includeVersion": true,
   "logLevel": "Verbose"

~/projects/agoric-sdk$ yarn typedoc
...

~/projects/agoric-sdk$ tar cf ~/time.tar api-docs/modules/agoric_time.md api-docs/interfaces/agoric_time.*

then in this repo:

~/projects/documentation/main tar xf ~/time.tar

[Chris-Hibbert]

for reference...

Ahh. Thanks. I didn't know about specifying plugins in typedoc.json, but I was able to get a .html version so I could see what was generated. I hope there isn't a huge difference.

[dckc]

@LuqiPan can you tell why https://docs.agoric.com/reference/agoric-sdk/modules/agoric_time is missing TimerService etc?

This PR should be largely obsolete as of #1038 , but the above page is missing a lot of stuff that this PR produces: https://dc-timer-ref.documentation-7tp.pages.dev/api-docs/modules/agoric_time.html

[LuqiPan]

These are the relevant logs for time package when building on CF:

21:25:31.883	[info] Converting project at ./packages/time
21:25:31.883	[debug] Using TypeScript 5.5.0-dev.20240327 from ./node_modules/typescript/lib
21:25:31.883	[debug] Expanded ./packages/time/src/timeMath.js to:
21:25:31.883		./packages/time/src/timeMath.js
21:25:31.883	[debug] Expanded ./packages/time/src/types.js to:
21:25:31.884		./packages/time/src/types.js
21:25:32.319	[debug] Converting with 1 programs 2 entry points
21:25:32.488	[debug] Finished getting entry points in 605ms
21:25:32.488	[debug] Begin readme.md/package.json search at ./packages/time
21:25:32.490	[debug] Finished conversion in 1ms
21:25:32.490	[warning] TimeMathType, defined in ./packages/time/src/types.d.ts, is referenced by timeMath.TimeMath but not included in the documentation.
21:25:32.490	[debug] Validation took 0ms

These are the logs when building on agoric-sdk/master:

[info] Converting project at ./packages/time
[debug] Using TypeScript 5.5.0-dev.20240327 from ./node_modules/typescript/lib
[debug] Expanded ./packages/time/src/timeMath.js to:
	./packages/time/src/timeMath.js
[debug] Expanded ./packages/time/src/types.js to:
	./packages/time/src/types.js
[debug] Converting with 1 programs 2 entry points
[debug] Finished getting entry points in 336ms
[debug] Begin readme.md/package.json search at ./packages/time
[debug] Finished conversion in 2ms
[warning] TimeMathType, defined in ./packages/time/src/types.d.ts, is referenced by timeMath.TimeMath but not included in the documentation.
[debug] Validation took 0ms

Looks pretty similar. Is TypeScript 5.5.0 affecting things?

[LuqiPan]

TypeScript 5.4.3 still yielded similar results:

[info] Converting project at ./packages/time
[debug] Using TypeScript 5.4.3 from ./node_modules/typescript/lib
[debug] Expanded ./packages/time/src/timeMath.js to:
	./packages/time/src/timeMath.js
[debug] Expanded ./packages/time/src/types.js to:
	./packages/time/src/types.js
[debug] Converting with 1 programs 2 entry points
[debug] Finished getting entry points in 264ms
[debug] Begin readme.md/package.json search at ./packages/time
[debug] Finished conversion in 1ms
[warning] TimeMathType, defined in ./packages/time/src/types.d.ts, is referenced by timeMath.TimeMath but not included in the documentation.
[debug] Validation took 0ms

@dckc did you remember roughly with what git hash you built the .md files in this PR?

[dckc]

@dckc did you remember roughly with what git hash you built the .md files in this PR?

I think I used
Agoric/agoric-sdk@b4c1e63

based on notes in Agoric/agoric-sdk#9131

It's strange... the "Defined in" links to to, for example, https://github.com/Agoric/agoric-sdk/blob/b78dc2aa5/packages/time/src/types.d.ts#L174

but that's 404. as is Agoric/agoric-sdk@b78dc2aa5

I don't seem to have that one locally either.

[github-actions]

Cloudflare deployment logs are available here

[dckc]

PTAL.