SolDoc

A documentation generator for solidity projects, inspired by TypeDoc.

Usage

SolDoc can be used as a CLI app or as a library and called from your code.

As a CLI tool

1. Install: yarn global add @soldoc/soldoc / npm i -g @soldoc/soldoc.
2. Use the CLI:

   Usage: cli.js --in <input dir> -o <out dir>
   
   Options:
   --help          Show help                                            [boolean]
   --version       Show version number                                  [boolean]
   --options       Path to JSON config file
   --in            Specifies the location the input files should be read from.
                                               [string] [default: "./contracts"]
   --json, -j      Output the parsed information to a json file instead of
                   rendering.                                            [string]
   --out, -o       Specifies the location the documentation should be written to. [string] [default: "./docs"]
   --quiet, -q     No stdout output                    [boolean] [default: false]
   --theme, -t     Specifies a npm module that exports a default
                   `render(filepath,contractName,contactInfo,options):
                   {content,extension}` function
                                           [string] [default: "@soldoc/markdown"]
   --repo-url, -r  Specifies remote repository url. Uses `repository` field in
                   `package.json` if available and not specified.        [string]
   --log, -l       Specifies the location the log file should be written to.
                                                                           [string]
   
   Examples:
   cli.js --in ./contracts -o ./docs  Render `.sol` files in `./contracts` into
                                       `.docs`
   
   For more information, visit https://github.com/dev-matan-tsuberi/soldoc
   

As a library

1. Install: yarn add --dev @soldoc/soldoc / npm i --save-dev @soldoc/soldoc.
2. Import in your project as:

   import soldoc from '@soldoc/soldoc';
   
   /* default options */
   soldoc.defaults = {
       in: './contracts',
       out: './docs',
       /* json: undefined, */
       /* repoUrl: undefined, */
       /* log: undefined, */
       quiet: false,
       theme: '@soldoc/markdown',
   };
   soldoc(options); // returns a promise

Themes

SolDoc is easily themeable, installing a theme is as simple as yarn add @soldoc/<theme> / npm i --save @soldoc/<theme> and setting a configuration option:

1. In the cli: soldoc --theme @soldoc/<theme>.
2. In code: soldoc({theme: '@soldoc/<theme>'}).

Currently the official themes are:

1. @soldoc/markdown *Default* - A simple markdown theme.
2. @soldoc/json - A theme that just outputs a JSON object.
3. Create a theme!

You can pass custom options to <theme> under it's name, example:

options.json

{
    ...
    "theme": "@soldoc/markdown",
    "@soldoc/markdown": {
       ...
    }
}

Contribute

Get started:

1. git clone git@github.com:dev-matan-tsuberi/soldoc.git && cd soldoc
2. yarn
3. yarn lerna bootstrap
4. Done.

Note: This project is managed as a monorepo and uses lerna.js.

This project needs contributors! Pull requests are very welcome and needed. Check out issues with label help wanted to get started.