I’m happy to announce the latest release of
solidity-docgen, our documentation generator for Solidity projects.
There are some breaking changes in this version with the goal of making the tool friendlier for the majority of users. The details and upgrade instructions are laid out in the Changelog and reproduced below.
Now that the defaults are sane, the next steps for the project are writing documentation and guides (embarrassingly meta!). I would like to create a full example project, including site generation and deployment, that can serve as a starting point for users.
To begin using
solidity-docgen, install it in a Solidity project and run
npx solidity-docgen. You should now see documentation for your contracts in Markdown format in the
docs directory. NatSpec comments will show up there as well. (These instructions will only work for Solidity 0.6 out of the box. For older versions see the note below about
--solc-module.) You can now publish these Markdown documents using something like GitHub Pages or a static site generator.
- Changed default output structure. The new default is equivalent to the old
If you were using
--contract-pages, you should remove it, since it is the new default. If you were using the previous defaults, you should now use
--output-structure single if you want a single page with all contracts, or
--output-structure readmes if you use READMEs to structure your output pages.
- Removed the default prelude template.
The prelude is an advanced feature that most users will not care about. It can be used to create cross-references in your documentation. If you were using the default templates before and you would like to keep the prelude, you will have to copy them into your project. Take
prelude.sample.hbs from the
templates directory, rename the latter to
prelude.hbs, and put them in a directory in your project. Then invoke
solidity-docgen with the
-t <templates-directory> option.
Nicer Alternative solc Support
(Released in 0.5.2)
--solc-moduleoption to use Node module resolution algorithm.
For example, if you’ve installed
solidity-docgen, you can now run
solidity-docgen --solc-module solc, where previously it would have been
solidity-docgen --solc-module ./node_modules/solc.
This is a small breaking change. If you were using this option before, you need to make sure its value is now something that Node recognizes as a module, such as the name of an installed Node module or a path beginning with