ūüíĶ Website Ad Revenue Calculator

Doxity library - documentation generator for solidity

Doxity Features

  • Document contracts and methods from your code automatically.

  • Build HTML documentation websites that can be hosted on GitHub.

  • React.js allows for complete customisation of output.

  • The UX from semantic-ui is very minimalistic.

  • Solidity Syntax highlighting

  • For each contract, options for whitelisting

    • Methods Documentation

    • ABI

    • Bytecode

    • Source Code

Doxity Installation

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


You can install `@digix/doxity` locally:

npm install --save-dev @digix/doxity

Orr globally in your project:

npm install -g @digix/doxity

Doxity quickstart

  1. You should have a project that contains

    1. natspecced* .sol contracts in a contracts directory

    2. package.json

    3. README.md

  2. doxity init command will clone and set up the boilerplate gatsby project - files can be found in ./scripts/doxity

  3. doxity build command will generate static HTML containing documentation to ./docs

Customise Markup and Publish it to GitHub

  1. doxity develop command will start a development server for editing the Gatsby project

  2. doxity compile command will compile the contracts and update the contract data

  3. Ensure you have set linkPrefix in scripts/doxity/config.toml to be equal to your repo's name (e.g. /my-project)

  4. doxity publish will generate static HTML containing documentation to ./docs

  5. After publishing, you'll end up with a ./docs folder in your project, which can be easily deployed

  6. Push it to master(or main) on GitHub

  7. Go to your repo options, update 'Github Pages -> Set Source' to 'master branch /docs folder.'

  8. Your documentation is live! Why not set up a Travis CI script to automate that whenever you commit?

Doxity Usage

.doxityrc file

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 generaHTMLhtrelativeethe  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
    }
  }
}


Doxity documentation Command Line Interface (CLI)

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 on saving 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].