Doxity

0.4.0 now works with truffle! 💻

Documentation Generator for Solidity

Demo Site

Uses gatsby to generate beautiful Solidity docs automatically via natspec.

Features

Automatically document contracts and methods from your code
Generate static HTML documentation websites that can be served directly from github
Fully customizable output using React
Minimalist UX from semantic-ui
Solidity Syntax highlighting
For each contract, options for whitelisting
- Methods Documentation
- ABI
- Bytecode
- Source Code

Installation

You can install @digix/doxity globally or locally in your project.

You'll also need solc 0.4.X (native until solc-js is supported) and libssl-dev installed on your machine.

# globally
npm install -g @digix/doxity
# or within project folder
npm install --save-dev @digix/doxity

Quickstart

Have a project that contains natspecced* .sol contracts in a contracts directory, a package.json and README.md.
doxity init will clone and set up the boilerplate gatsby project - files found in ./scripts/doxity
doxity build will generate static HTML containing documentation to ./docs

Customize Markup and Publish it to github

doxity develop will start a development server for editing gatsby project
doxity compile will compile the contracts and update the contract data
Ensure you have set linkPrefix in scripts/doxity/config.toml to be equal to your repo's name (e.g. /my-project)
doxity publish will generate static HTML containing documentation to ./docs
After publishing, you'll end up with a ./docs folder in your project which can be easily deployed
Push it to master on github
Go to your repo options, update 'Github Pages -> Set Source' to 'master branch /docs folder'
Your documentation is live! Why not set up a Travis CI script to automate that whenever you commit?

* N.B. Currently Solidity doesn't support multiple @return values. Pass it a JSON object until it's patched. EG:

// natspec example - appears above each method
/**
@notice Get user's information from their EOA/Contract address
@dev Some more techncial explanation here
@param _account the EOA or contract address associated with the user
@param _anotherParam this is just an example of passing a second param
@return {
  "_feeaccount": "The contract address for storage fee payments",
  "_recastaccount": "The contract address for recasting tokens",
  "_assetcount": "The number of items associated with this account",
  "_assetstartindex": "The starting index of the user's items collection"
}
*/
function getUser(address _account) ...

Usage

`.doxityrc`

You can configure all of doxity's options using a .doxityrc file at the root of your project, with the following structure:

// .doxityrc
{
  // gatsby project source files directory
	"target": "scripts/doxity",
  // folder that contains the contracts you want to compile
	"src": "contracts/*",
  // folder in gatsby project to dump contract data
	"dir": "pages/docs",
  // folder to output the generated html (relative to project root)
	"out": "docs",
  // tarball for bootstrapping the gatsby project
  "source": "https://github.com/DigixGlobal/doxity-gatsby-starter-project/archive/9445d59056058159ce25d7cd1643039523718553.tar.gz",
  // for truffle projects, you can get deployed contract info
  // use https://github.com/DigixGlobal/doxity-gatsby-starter-project/archive/74df3b2b7a2484714540e4a9153a8f1d0f95a380.tar.gz for experimental interactive mode!
  "interaction": {
    "network": "2",
    "providerUrl": "https://morden.infura.io/sign_up_to_get_a_hash"
  }
  // option to whitelist various data
  "whitelist": {
    // the keyname `all` will be used for whitelist defaults
    "all": {
      "abi": true,
      "methods": true,
      "bytecode": false, // bytecode is false or undefined, it won't be shown
      "source": false // source is false or undefined, won't be shown
    },
    "DigixMath": {
      "source": true // source code uniquely shown for this contract, bytecode still hidden
    }
  }
}

Command Line Interface

You can also override these options by passing them to a command tool.

Unless you override them, default arguments will be used:

doxity init --target --source (with init, you can also pass any arguments to save them to .doxityrc)
doxity compile --target --src --dir
doxity develop --target
doxity publish --target --out

When passing to src in the CLI, wrap the filename in quotes; e.g. --src "contracts/*" - it is passed directly to solc.

Protip: If you are installing locally, you could add the following to your package.json:

"scripts" : {
  "docs:init": "node_modules/.bin/doxity init", // add your custom arguments (see API below)
  "docs:compile": "node_modules/.bin/doxity compile",
  "docs:develop": "node_modules/.bin/doxity develop",
  "docs:publish": "node_modules/.bin/doxity publish",
  "docs:build": "node_modules/.bin/doxity build", // compile + publish
  ...
},

You can then use npm run docs:[command] as a proxy for doxity [command].

TODO

1.0.0
- AST parsing (pending solidity update)
  - pragma version
  - Imports
  - Modifiers, variables, private functions, etc.
  - Sourcemaps
  - Inline Code Snippets
- Tree view
- Methods filtering
- Tests
1.x
- Multiple Versioning
- Pudding integration? Automatically generate forms + web3 instance for testing via GUI?

License

BSD-3-Clause 2016

yudilevi/doxity