docs(contracts): setup solidity docgen and configure it to work on docusaurus #870

ctrlc03 · 2023-12-04T15:36:36Z

This PR adds support for Solidity Docgen as well as fixes syntax errors in current NatSpec comments (note it does not enhance the comments as that is to be worked on #843). Support for hosting the generated content on Docusaurus is also added

contracts/contracts/MACI.sol

contracts/contracts/MessageProcessor.sol

contracts/contracts/Tally.sol

contracts/package.json

website/package.json

website/src/scripts/setupSolidityDocs.ts

samajammin

Nice work! Looks good overall but added some change requests.

netlify · 2023-12-06T19:25:35Z

✅ Deploy Preview for maci-typedoc ready!

Name	Link
🔨 Latest commit	`3101a60`
🔍 Latest deploy log	https://app.netlify.com/sites/maci-typedoc/deploys/657832b3dc3d090008950453
😎 Deploy Preview	https://deploy-preview-870--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.

.github/workflows/gh-pages.yml

ctrlc03 · 2023-12-11T10:14:28Z

I have some thoughts for the typedocs and soliditydocs, but not really related to this PR. Try to put some thoughts here though, if it's not a proper place, then we could move to open a new discussion thread, or somewhere else.

First of all, I wanna ask that if there's version difference between different versions? For example, the circuits.md file is different in v0.x and v1.x. Will type docs and solidity docs also have this difference? Such as changing type from Int to BigInt for some arguments in different versions. If so, I would suggest to have this kind of document structure: Also it's clearer for me that both typedoc and soliditydocs are belong to Documents, instead of separating them on the navbar.

Second, I also suggest to split PR into docgen related one and NatSpec one.

Last is I think the netlify is not displaying correct website?

@kittybest For v0.x vs v1.x - we will continue to host v0.x docs (legacy) but do not intend to update them or touch them at all. These are just a reference of how MACI v.0x works (though we do not support it anymore). Moving forward, all new content will only be inside v.1x or newer versions. TLDR no typedoc nor natspec docs for v.0x

Sure we can put them in the documents folder as highlighted by that image, though we will not be making typedoc related changes on this PR, but please feel free to open one yourself to move them.

While I agree that the natspec could have been moved to a separate one (which is also coming today), some of the tags were broken and were preventing docgen to complete. Would it be ok to keep it like this for now, just change the folder where the docs are hosted?

Not sure what you mean by not displaying the correct website? what is wrong about it?
Currently: Netlify: preview only - GH pages with custom domain: deploys on pushes to dev

samajammin · 2023-12-11T15:54:31Z

@ctrlc03 FYI looks like builds are failing in Netlify:

6:09:24 AM: $ ./.github/scripts/website.sh
6:09:24 AM: bash: ./.github/scripts/website.sh: No such file or directory
6:09:24 AM: 
6:09:24 AM: "build.command" failed                                        
6:09:24 AM: ────────────────────────────────────────────────────────────────
6:09:24 AM: 
6:09:24 AM:   Error message
6:09:24 AM:   Command failed with exit code 127: ./.github/scripts/website.sh (https://ntl.fyi/exit-code-127)
6:09:24 AM: 
6:09:24 AM:   Error location
6:09:24 AM:   In Build command from Netlify app:
6:09:24 AM:   ./.github/scripts/website.sh
6:09:24 AM: 
6:09:24 AM:   Resolved config
6:09:24 AM:   build:
6:09:24 AM:     command: ./.github/scripts/website.sh
6:09:24 AM:     commandOrigin: ui
6:09:24 AM:     environment:
6:09:24 AM:       - REVIEW_ID
6:09:24 AM:     publish: /opt/build/repo/website/build
6:09:24 AM:     publishOrigin: ui
6:09:25 AM: Failed during stage "building site": Build script returned non-zero exit code: 2
6:09:25 AM: Build failed due to a user error: Build script returned non-zero exit code: 2
6:09:25 AM: Failing build: Failed to build site
6:09:25 AM: Finished processing build request in 19.439s

Is Netlify able to access that script? 🤔

ctrlc03 · 2023-12-11T15:58:04Z

@ctrlc03 FYI looks like builds are failing in Netlify:

6:09:24 AM: $ ./.github/scripts/website.sh
6:09:24 AM: bash: ./.github/scripts/website.sh: No such file or directory
6:09:24 AM: 
6:09:24 AM: "build.command" failed                                        
6:09:24 AM: ────────────────────────────────────────────────────────────────
6:09:24 AM: 
6:09:24 AM:   Error message
6:09:24 AM:   Command failed with exit code 127: ./.github/scripts/website.sh (https://ntl.fyi/exit-code-127)
6:09:24 AM: 
6:09:24 AM:   Error location
6:09:24 AM:   In Build command from Netlify app:
6:09:24 AM:   ./.github/scripts/website.sh
6:09:24 AM: 
6:09:24 AM:   Resolved config
6:09:24 AM:   build:
6:09:24 AM:     command: ./.github/scripts/website.sh
6:09:24 AM:     commandOrigin: ui
6:09:24 AM:     environment:
6:09:24 AM:       - REVIEW_ID
6:09:24 AM:     publish: /opt/build/repo/website/build
6:09:24 AM:     publishOrigin: ui
6:09:25 AM: Failed during stage "building site": Build script returned non-zero exit code: 2
6:09:25 AM: Build failed due to a user error: Build script returned non-zero exit code: 2
6:09:25 AM: Failing build: Failed to build site
6:09:25 AM: Finished processing build request in 19.439s

Is Netlify able to access that script? 🤔

there was a name mismatch, fixed now on our side.

samajammin · 2023-12-12T05:33:17Z

website/src/scripts/setupSolidityDocs.ts

+      let fileContent = fs.readFileSync(absolutePath, "utf8");
+
+      // Remove the "# Solidity API" line
+      fileContent = fileContent.replace("# Solidity API\n", "");


integrationTests/tsconfig.json

samajammin · 2023-12-12T05:40:46Z

website/src/scripts/setupSolidityDocs.ts

+import fs from "fs";
+import path from "path";
+
+const solidityDocDir = path.resolve(__dirname, "../../versioned_docs/version-v1.x/natspec-docs");


I'd suggest maybe solidity-api or contracts-api or solidity-docs instead of natspec-docs. Subjective take but I suspect many folks don't know what NatSpec is & may get confused.

I wonder if there's also a way to specify the display name of the directory (e.g. to "Solidity docs" or "Solidity API") 🤔

I think we can accomplish that with a custom sidebar, can do that in a later PR if you want - we can directly specify order and name there

I think we can accomplish that with a custom sidebar, can do that in a later PR if you want - we can directly specify order and name there

Sweet, love that idea!

samajammin · 2023-12-12T05:41:23Z

website/src/scripts/setupSolidityDocs.ts

+import path from "path";
+
+const solidityDocDir = path.resolve(__dirname, "../../versioned_docs/version-v1.x/natspec-docs");
+const sourceDir = path.resolve(__dirname, "../../../contracts/docs");


Add comment that we pull generated docs from the contracts package?

samajammin

LGTM! A couple comments but no blockers.

I didn't scrutinize the contract comments closely but website looks great & all pages are searchable! 🎉

…ocusaurus

…gger in workflow

…y inherited functions in solidity docgen docs

…y on the NatSpec comments for all Solidity files, document the scripts used within the website folder to fix typedoc and natspec links

…for NatSpec docs

…nning typedoc, and solidity docgen) in order to allow preview via netlify

baumstern

Great work, thanks!

ctrlc03 self-assigned this Dec 4, 2023

ctrlc03 requested review from baumstern, samajammin and 0xmad December 4, 2023 16:10