docs(typedoc): Typedoc Indexing #896

kittybest · 2023-12-11T09:27:38Z

Description
Try the package docusaurus-plugin-typedoc at the beginning, it could automatically generate markdown files for typedocs, and put them inside doc/ folder, which is default for the Next version document in Docusaurus. Also the sidebar will also be auto-generated.
However, we will need to do something before we actually start or build the docusaurus:

replace the package folder link in README.md (which should be the index page of typedoc) to github links. (currently we are doing it in the setupTypedoc.ts, by replacing the route in html file ➡️

maci/website/src/scripts/setupTypedoc.ts

Line 38 in 88bfae9

'<a target="_parent" href="https://github.com/privacy-scaling-explorations/maci/tree/dev/',
docs/ is not the actual folder we put our documents, so will also need to move or copy the whole typedoc/ folder to versioned_docs/v1.x/.

It's hard to split the command in docusaurus-plugin-typedoc, so I instead, tried to use only typedoc-plugin-markdown. I put the scripts doing the above 2 steps in the setupTypedoc.ts file.

But there's still a problem, that the sidebar name is not setup as Typedoc. I will fix it.

Also wanna ask that the if we wanna auto-generate the index page of typedoc from the README.md? or we wanna write our own?

Last is that should we put the generated markdown files in the repo instead of ignoring them?

netlify · 2023-12-11T09:27:43Z

✅ Deploy Preview for maci-typedoc ready!

Name	Link
🔨 Latest commit	`1f7a509`
🔍 Latest deploy log	https://app.netlify.com/sites/maci-typedoc/deploys/657c5becadafdc0008ef8759
😎 Deploy Preview	https://deploy-preview-896--maci-typedoc.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

ctrlc03 · 2023-12-11T10:39:41Z

Description Try the package docusaurus-plugin-typedoc at the beginning, it could automatically generate markdown files for typedocs, and put them inside doc/ folder, which is default for the Next version document in Docusaurus. Also the sidebar will also be auto-generated. However, we will need to do something before we actually start or build the docusaurus:

replace the package folder link in README.md (which should be the index page of typedoc) to github links. (currently we are doing it in the setupTypedoc.ts, by replacing the route in html file ➡️

maci/website/src/scripts/setupTypedoc.ts

Line 38 in 88bfae9

'<a target="_parent" href="https://github.com/privacy-scaling-explorations/maci/tree/dev/',

docs/ is not the actual folder we put our documents, so will also need to move or copy the whole typedoc/ folder to versioned_docs/v1.x/.

It's hard to split the command in docusaurus-plugin-typedoc, so I instead, tried to use only typedoc-plugin-markdown. I put the scripts doing the above 2 steps in the setupTypedoc.ts file.

But there's still a problem, that the sidebar name is not setup as Typedoc. I will fix it.

Also wanna ask that the if we wanna auto-generate the index page of typedoc from the README.md? or we wanna write our own?

Last is that should we put the generated markdown files in the repo instead of ignoring them?

I would suggest to .gitignore them - anyways they will be generated on the gh-pages branch upon deployment

samajammin · 2023-12-12T06:02:40Z

docs/ is not the actual folder we put our documents, so will also need to move or copy the whole typedoc/ folder to versioned_docs/v1.x/.

Hmmm so is the takeaway that docusaurus-plugin-typedoc doesn't support versioned docs? That seems surprising... feels like a pretty common use of Docusarus 🤔 In any case, sounds like you found a solution to copy them over to the write location.

But there's still a problem, that the sidebar name is not setup as Typedoc. I will fix it.

What's the current name - is it the same as the directory slug? If so, I noticed the same issue in (#870 (comment))

Also wanna ask that the if we wanna auto-generate the index page of typedoc from the README.md? or we wanna write our own?

Do we need an index page? Happy to write our own if so - I can add a quick explainer. Better yet, why don't you take a quick swing at a description for it (e.g. these API docs are generated using TypeDoc for xyz packages of the repo).

Last is that should we put the generated markdown files in the repo instead of ignoring them?

I agree with @ctrlc03 I think we can gitignore these since they're autogenerated.

kittybest · 2023-12-12T15:51:04Z

Do we need an index page? Happy to write our own if so - I can add a quick explainer. Better yet, why don't you take a quick swing at a description for it (e.g. these API docs are generated using TypeDoc for xyz packages of the repo).

Currently use the modules.md page as the index page, if anyone wants to add any description on the page, just leave a comment :) or it could be an independent issue~~

What's the current name - is it the same as the directory slug? If so, I noticed the same issue in (#870 (comment))

Yes it's actually the same question. Now it's automatically generated as just index.md (since this file is its homepage).
Since they are the same question, I think we could open an issue to deal with it, not modifying it on this branch, that would be clearer.

ctrlc03

Great stuff, thanks for taking care of this. Left just a couple of minor comments

ctrlc03 · 2023-12-14T09:37:57Z

website/.gitignore

I would also add the typedoc folder directly as someone might generate the docs but not actually run the build script inside the website folder

ctrlc03 · 2023-12-14T09:38:06Z

website/src/scripts/setupSolidityDocs.ts

@@ -1,39 +1,13 @@
 import fs from "fs";
 import path from "path";

+import { copyDirectory } from "./utils";


ctrlc03 · 2023-12-14T09:42:11Z

website/src/scripts/setupTypedoc.ts

+try {
+  const versionContent = fs.readFileSync(versionFile, "utf8");
+  if (versionContent) {
+    const versionContentJson: string[] = JSON.parse(versionContent) as string[];


you can remove : string[] as it's redundant (given you cast using as string[])

ctrlc03 · 2023-12-14T09:50:01Z

website/src/scripts/setupTypedoc.ts

-  }
+const TYPEDOC_DIR = path.resolve(__dirname, "../../typedoc");
+
+function updateMentionFiles(dirName: string) {


can we add some documentation to this function please?

…n website/.gitignore

ctrlc03

Great stuff, thank you!!

samajammin · 2023-12-15T14:52:34Z

package.json

@@ -6,7 +6,7 @@
  "license": "MIT",
  "scripts": {
    "bootstrap": "lerna bootstrap",
-    "build": "lerna run build",
+    "build": "lerna run build --ignore=website",


Why ignore website here? I suppose generally not needed when building MACI?

Because we could only run npm run typedoc in root folder only after all the packages are built (instead of website). The npm run build command in website/ would do things to Typedocs and put them in the versioned_docs/v1.x/ folder. Which means the runnable order of the script should be

build all packages

build typedoc and soliditydocs

build website

Of course we could ignore the setup-typedoc and setup-soliditydocs command for the first build while running lerna run build command, and build typedocs and soliditydocs, and build the website again; but I don't think we should build the website twice. That's why I ignore the website package for the first build.

samajammin · 2023-12-15T14:55:04Z

I think we could open an issue to deal with it, not modifying it on this branch, that would be clearer.

@kittybest agreed - do you mind creating an issue to capture this?

Nice work on the PR!

kittybest changed the base branch from dev to docs/contracts December 11, 2023 09:28

ctrlc03 force-pushed the docs/contracts branch from 88bfae9 to 91c915a Compare December 11, 2023 14:09

ctrlc03 requested review from ctrlc03 and removed request for ctrlc03 December 11, 2023 14:30

ctrlc03 assigned kittybest Dec 11, 2023

ctrlc03 force-pushed the docs/contracts branch 2 times, most recently from 04586fb to 5700f1f Compare December 11, 2023 15:58

ctrlc03 force-pushed the docs/contracts branch 2 times, most recently from 8455b1d to 3101a60 Compare December 12, 2023 10:15

Base automatically changed from docs/contracts to dev December 12, 2023 11:55

samajammin added this to the MACI v1.1.1 refactor milestone Dec 12, 2023

kittybest force-pushed the try-typedoc-md branch 2 times, most recently from d133620 to 9cf10f9 Compare December 13, 2023 16:37

kittybest marked this pull request as ready for review December 13, 2023 16:55

kittybest force-pushed the try-typedoc-md branch 2 times, most recently from a27964a to 633666f Compare December 14, 2023 08:24

ctrlc03 requested changes Dec 14, 2023

View reviewed changes

ctrlc03 force-pushed the try-typedoc-md branch from c14e269 to 14d5477 Compare December 14, 2023 09:53

kittybest added 2 commits December 15, 2023 14:00

feat: build typedoc for website

bd75ea4

chore: add description to updateMentionFiles function, add typedoc/ i…

1f7a509

…n website/.gitignore

ctrlc03 force-pushed the try-typedoc-md branch from 34075d4 to 1f7a509 Compare December 15, 2023 14:00

ctrlc03 self-requested a review December 15, 2023 14:15

ctrlc03 approved these changes Dec 15, 2023

View reviewed changes

ctrlc03 merged commit b64488b into dev Dec 15, 2023
12 checks passed

ctrlc03 deleted the try-typedoc-md branch December 15, 2023 14:40

samajammin reviewed Dec 15, 2023

View reviewed changes

ctrlc03 linked an issue Dec 15, 2023 that may be closed by this pull request

Add TypeDoc to search #884

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(typedoc): Typedoc Indexing #896

docs(typedoc): Typedoc Indexing #896

kittybest commented Dec 11, 2023 •

edited

Loading

netlify bot commented Dec 11, 2023 •

edited

Loading

ctrlc03 commented Dec 11, 2023 •

edited

Loading

samajammin commented Dec 12, 2023

kittybest commented Dec 12, 2023

ctrlc03 left a comment

ctrlc03 Dec 14, 2023 •

edited

Loading

ctrlc03 Dec 14, 2023

ctrlc03 Dec 14, 2023

ctrlc03 Dec 14, 2023

ctrlc03 left a comment

samajammin Dec 15, 2023

kittybest Dec 15, 2023

samajammin commented Dec 15, 2023

docs(typedoc): Typedoc Indexing #896

docs(typedoc): Typedoc Indexing #896

Conversation

kittybest commented Dec 11, 2023 • edited Loading

netlify bot commented Dec 11, 2023 • edited Loading

✅ Deploy Preview for maci-typedoc ready!

ctrlc03 commented Dec 11, 2023 • edited Loading

samajammin commented Dec 12, 2023

kittybest commented Dec 12, 2023

ctrlc03 left a comment

Choose a reason for hiding this comment

ctrlc03 Dec 14, 2023 • edited Loading

Choose a reason for hiding this comment

ctrlc03 Dec 14, 2023

Choose a reason for hiding this comment

ctrlc03 Dec 14, 2023

Choose a reason for hiding this comment

ctrlc03 Dec 14, 2023

Choose a reason for hiding this comment

ctrlc03 left a comment

Choose a reason for hiding this comment

samajammin Dec 15, 2023

Choose a reason for hiding this comment

kittybest Dec 15, 2023

Choose a reason for hiding this comment

samajammin commented Dec 15, 2023

kittybest commented Dec 11, 2023 •

edited

Loading

netlify bot commented Dec 11, 2023 •

edited

Loading

ctrlc03 commented Dec 11, 2023 •

edited

Loading

ctrlc03 Dec 14, 2023 •

edited

Loading