Agoric / documentation

User documentation
https://agoric.com/documentation/
Apache License 2.0
15 stars 40 forks source link

include endo, agoric-sdk reference doc in search #927

Open dckc opened 6 months ago

dckc commented 6 months ago

@LuqiPan suggested it.

I like the idea enough to make an issue for it :)

### Tasks
- [ ] https://github.com/endojs/endo/pull/2185
- [ ] https://github.com/Agoric/agoric-sdk/pull/9146
- [ ] https://github.com/Agoric/documentation/pull/1038
dckc commented 5 months ago

TypeError from typedoc plugin for vitepress (solved)

@0xpatrickdev noted typedoc-plugin-markdown Vitepress theme

I tried it out today, but without luck: I started at agoric-sdk version: 2024-02-23 19:35 fd0382de8

followed the quickstart instructions yarn add typedoc typedoc-plugin-markdown@next typedoc-vitepress-theme@next --dev to get...

diff --git a/package.json b/package.json
index 5ee1a4f85..e9bb2a0dd 100644
--- a/package.json
+++ b/package.json
@@ -34,6 +34,8 @@
     "prettier-plugin-jsdoc": "^1.0.0",
     "type-coverage": "^2.27.1",
     "typedoc": "^0.25.7",
+    "typedoc-plugin-markdown": "^4.0.0-next.53",
+    "typedoc-vitepress-theme": "^1.0.0-next.0",
     "typescript": "^5.3.3"
   },
   "engines": {
diff --git a/typedoc.json b/typedoc.json
index 685abaab4..9853ceb79 100644
--- a/typedoc.json
+++ b/typedoc.json
@@ -6,6 +6,7 @@
     "packages/cosmic-proto/"
   ],
   "name": "API documentation of Agoric SDK ",
+  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
   "entryPointStrategy": "packages",
   "out": "api-docs",
   "includeVersion": true,
$ yarn typedoc
yarn run v1.22.19
$ /home/connolly/projects/agoric-sdk/node_modules/.bin/typedoc
[info] Loaded plugin typedoc-plugin-markdown
[error] The plugin typedoc-vitepress-theme could not be loaded.
[error] TypeError: typedoc_plugin_markdown_1.MarkdownPluginOptionsReader is not a constructor
    at load (/home/connolly/projects/agoric-sdk/node_modules/typedoc-vitepress-theme/dist/index.js:46:27)
    at loadPlugins (/home/connolly/projects/agoric-sdk/node_modules/typedoc/dist/lib/utils/plugins.js:31:23)
    at async Application.bootstrapWithPlugins (/home/connolly/projects/agoric-sdk/node_modules/typedoc/dist/lib/application.js:194:13)
    at async main (/home/connolly/projects/agoric-sdk/node_modules/typedoc/dist/lib/cli.js:42:15)

cc @turadg

p.s. progress with typedoc-plugin-markdown alone

@0xpatrickdev suggested, in packages/zoe:

yarn add -D typedoc typedoc-plugin-markdown
yarn prepack
yarn typedoc --plugin typedoc-plugin-markdown --out typedoc-gen src/*

# see markdown in typedoc-gen

and I was able to reproduce his results.

It lacks navigation links. @0xpatrickdev suggested https://www.npmjs.com/package/vitepress-sidebar looks like a popular approach.

dckc commented 4 months ago

fixed in #1038

let's track #1041 under #1031

and I think we talked about making #1046 a lower priority

dckc commented 4 months ago

We're reconsidering this approach: https://github.com/Agoric/documentation/issues/1032#issuecomment-2052134295