Solidity Docgen 0.5

General Announcements
1

cover_forum_solidity_docgen0.5
cover_forum_solidity_docgen0.52400×1350 204 KB

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.

Enjoy!

Output Structure

  • Replaced --contract-pages with --output-structure [contracts|readmes|single].
  • Changed default output structure. The new default is equivalent to the old --contract-pages.

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.

Default Prelude

  • 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 contract.hbs and 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)

  • Changed --solc-module option to use Node module resolution algorithm.

For example, if you’ve installed solc@0.5 alongside 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 ./, ../, or /.

3 Likes