Doxity
0.4.0 now works with truffle! 💻
Documentation Generator for Solidity
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 acontracts
directory, apackage.json
andREADME.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 projectdoxity compile
will compile the contracts and update the contract data- Ensure you have set
linkPrefix
inscripts/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
- AST parsing (pending solidity update)
- 1.x
- Multiple Versioning
- Pudding integration? Automatically generate forms + web3 instance for testing via GUI?
License
BSD-3-Clause 2016