Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gnark docs need love #1183

Open
thor314 opened this issue Jun 27, 2024 · 1 comment
Open

gnark docs need love #1183

thor314 opened this issue Jun 27, 2024 · 1 comment
Labels
consolidate strengthen an existing feature doc

Comments

@thor314
Copy link

thor314 commented Jun 27, 2024

I spent the last hour trying to run gnark, and have not yet succeeded. I'm sure I'll get there eventually, but it's pretty bad rn.

I kept a dev log.

https://gist.github.com/thor314/245e25d23eb1f9628f347162dea8d409

@ivokub
Copy link
Collaborator

ivokub commented Jun 28, 2024

Yeah, we completely agree - docs.gnark.io is stale. The main issue there is that it is difficult to keep the documentation site and gnark consistent with each other, there are no automated tools.

We're now slightly taking a different approach - instead of separate documentation we implement example as Go doctests as they are testable in CI and when running Go tests. But we do not have sufficient number of tests and they are rather for more complex circuits (a la pairing, field emulation etc, see https://pkg.go.dev/github.com/consensys/[email protected]/std/math/emulated#example-Field for example).

Now, the issue with this approach is that such examples look good only on pkg.go.dev/github.com/consensys/gnark and may be unintuitive to look for in the repo directly. So, we're also thinking about compiling godoc into a Markdown/RST which can be included in the repository directly. (see also issues #460 #525).

And finally, we should add a lot more examples in examples/ subfolder, maybe renaming the packages with increasing order of difficulty (01-install, 02-simple, 03-witness-assignment etc. etc) so that the users could do step-by-step and progress a little bit by learning only a few concepts at a time.

All this is known and planned, we're currently very busy with Linea zkevm, but will come back to general improvement topics soon.

@ivokub ivokub added consolidate strengthen an existing feature doc labels Jun 28, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
consolidate strengthen an existing feature doc
Projects
None yet
Development

No branches or pull requests

2 participants