gnark docs need love

[thor314]

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]

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.