Publish the rust-docs in GH pages for easier usage and access

[ed255]

No description provided.

[ryanycw]

Hey guys, I wonder if this issue is up-to-date. If yes, I would love to have the chance to pick up this task.

[ChihChengLiang]

Hi @ryanycw, feel free to take this task! It is still valid!
A rust doc on the Github page would help contributors to get up to speed with the codebase better.

[ryanycw]

Hey guy, I've finished the basic manual doc generation. And I have two ideas in my mind to improve the process. One is to use a CI action to update the docs automatically. The second is to add a husky hook to update the docs in every commit.

I prefer the second approach since it won't add any risk to the repository by only running on the local repository. With the first approach, I've done some experiment. And it requires permissions to push the commit of updating the docs with GitHub actions, which is riskier for the project.

I want to ask for your opinions to see if there is anything I oversee and what your suggestions would be.

[ChihChengLiang]

Hi @ryanycw,
Good progress! Can you send a draft PR?
I checked the diff on your working branch and I have some comments.

We shouldn't check in the docs/ into the codebase. Instead, we should build the docs whenever we need them. I think by not checking in the docs/, many of the issues you described are resolved.

[ryanycw]

@ChihChengLiang Thank you for checking in on the progress! If I open a new branch and reproduce the work with a cleaner commit history, will it be easier for you to review it? I hope I can make your job easier :).

[ChihChengLiang]

Hi @ryanycw, please send a "Draft pull request" to https://github.com/privacy-scaling-explorations/zkevm-circuits.
A draft pull request doesn't have to be ready for review, but I can add comments to it for early feedback.

[ryanycw]

Hi @ChihChengLiang, thank you so much for the guidance. I've just sent the draft PR. Would love to hear your suggestions and comments.

[ryanycw]

Here is the result of what the GitBook will look like.
https://ryanycw.github.io/zkevm-circuits/zkevm_circuits/

It turns out that the permission issue isn't related to the deployment with GitHub.
It's related to the artifacts compressed file.
https://github.com/actions/upload-pages-artifact#file-permissions
actions/deploy-pages#188

And I've found the great work from the reth team.
They use the rust mdbook to make them look nicer.
I would be giving it a try today.
https://paradigmxyz.github.io/reth/
https://github.com/paradigmxyz/reth/blob/main/.github/workflows/book.yml

Update: I've given mdbook a shot, and it seems there is a format requirement to use that. So, I believe rust-docs is a more feasible solution at this moment.

[ChihChengLiang]

Hi @ryanycw,
The demo page looks great! I like it very much.

For mdbook, we have a documentation in mdbook style, too. It is https://github.com/privacy-scaling-explorations/zkevm-docs.

[ryanycw]

Hi @ChihChengLiang, Thank you again for all the guidance and support! I've published the pull request and asked for feedback in the comments.

In the meantime, can I ask for some directions on other issues that might be a good start to work on? I've gone through the good first issues, and most of them were assigned. I would love to work on #1194, but if there are other options I would like to keep #1194 to other first-time contributors since it would be a perfect start.