I would like to thank OZ team for a very quick ramp-up of this wonderful package, which has allowed us to auto-extract our contracts documentation into MD (MarkDown) files and make it properly visible on GitHub, GitBook and any other application or hosting-service which supports this format.
AFAIK, no other such package is currently viable specifically for Solidity (I have found a few projects, all of which seem to have been abandoned quite a while ago, and/or incomplete to a point which allows one to easily generate the docs).
This package is a pretty much “plug & play” utility, which makes it very easy to “get the job done” with almost zero effort. In addition to that, it also allows for advanced configuration of how your docs will appear, via an HBS (HandleBars) configuration file which is processed during execution.
For anyone interested, we have utilized this package in our repository:
This infrastructures allows us to generate our docs along with two other files:
Following that, we can publish the documentation on GitBook simply by registering our repository for this service (though the output docs must be added to the repo).
We (and anyone else seeking to do so) can auto-generate the docs via npm run docify
.
Thank you OZ!!!
3 Likes
Glad to hear that @barakman! For everyone else, here is the link to the repository.
There is basically no documentation for how to use this yet (ironic, right?) but if anyone is interested in using it I’m happy to guide through the setup. The default behavior of just running the command should be enough to get going, though.
2 Likes
Just for future reference, we’ve moved our official documentation to this repository, which installs our contracts via npm
.
This is instead of maintaining them under version-control along with the output of solidity-docgen
.
Outside of this context, though of possible interest to some readers:
We link this repository to GitBook here.
Thanks
1 Like
Hi @barakman,
Thanks for sharing.
It would be great if you wanted to post in #general:showcase about how the Bancor smart contract documentation is built.
1 Like
Hi @abcoathup.
Do you mean for me to create a new topic with something like “How to integrate solidity-docgen
into your project”?
1 Like
Hi @barakman,
A topic on “How to integrate solidity-docgen
into your project” would be fantastic.
I was originally thinking you could showcase your documentation generated using solidity-docgen
in #general:showcase
Either would be great to share with the community.
Sorry, I’m not really familiar with this community structure.
Should I open this topic at #general:showcase or elsewhere (and if elsewhere, then where)?
Thanks.
1 Like
Hi @barakman,
#general:showcase will be fine.
If you have any issues I can move it to the appropriate category.
OK, have been dealing with a bunch of urgent matters recently, but now done.
1 Like