今回はSolidityで書いたContractのドキュメントを自動生成するツールの紹介とその使い方のまとめです。
実業務を考えるとやっぱり、作ったプログラムのAPIリファレンスは自動生成できるようにしておいたほうが何かと便利ですよね。
今回利用したツールはこちら。
github.com
このツールをREADME.mdに書いてある通りに実行してもエラーが出るだけでドキュメントが生成できなかったので、ワークアラウンドをまとめます。
doxityのインストール
node.jsの環境はインストール済みの前提で進めます。doxityはnative solcを使うので事前にsolcをインストールしておく必要があります。(solcjsではダメです）
npm install @digix/doxity
doxityの初期化
node_modules/.bin/doxity init
これでscripts/doxity/以下にドキュメントのテンプレートがコピーされます。が、このコマンドなぜかよく
Error: EEXIST: file already exists, mkdir '/Users/nakajo/doxity-sample/scripts/doxity-tmp-Wed Dec 20 2017 09:10:17 GMT+0900 (JST)/doxity-gatsby-starter-project-a4886b7a7a04c018ac04fed3125d7d4785e74bed/components'
とエラーが出てこけるので、根気よく成功するまで実行します(ぇ
initに成功すると以下のファイルが作られます。
|--.doxityrc |--scripts | |--doxity | |--doxity-tmp-Wed Dec 20 2017 09:12:52 GMT+0900 (JST) | | |--doxity-gatsby-starter-project-a4886b7a7a04c018ac04fed3125d7d4785e74bed | | | |--components | | | | |--abi.js | | | | |--bytecode.js | | | | |--contract.js | | | | |--contractDropdown.js | | | | |--method.js | | | | |--methods.js | | | | |--shortAddressLink.js | | | | |--source.js | | | |--config.toml | | | |--css | | | | |--favicon.png | | | | |--hljs-atom-one.css | | | | |--responsive.css | | | | |--style.scss | | | |--gatsby-node.js | | | |--html.js | | | |--package.json | | | |--pages | | | | |--_template.jsx | | | | |--docs | | | | | |--_template.jsx | | | | |--index.md | | | |--wrappers | | | | |--json.jsx | | | | |--md.jsx | | |--.eslintrc | | |--.gitignore | | |--README.md
scripts/doxity/以下に本来生成されていなければいけないファイルがscripts/doxity-tmp-$(TimeStamp)/doxity-gatsby-starter-project-a4886b7a7a04c018ac04fed3125d7d4785e74bed/以下にあるのでコピーします。
cp -r scripts/doxity-tmp-Wed Dec 20 2017 09:12:52 GMT+0900 (JST)/doxity-gatsby-starter-project-a4886b7a7a04c018ac04fed3125d7d4785e74bed/* scripts/doxity/
ファイルをコピーしたらscripts/doxity/に移動してnpm initしてgatsbyなど必要なモジュールをインストールします。
cd scripts/doxity/ npm install
#doxityのinit.jsの中にはnpm installしてる箇所があったけど多分ファイルのコピーが違うディレクトリにされてるので動かなかったっぽい？ので手動でnpm installしてあげる必要があります。
これでdoxityの初期化は完了です。
ドキュメントを生成する
ドキュメントを生成するのに必須となるファイルが
- contracts/*.sol
- README.md
- package.json
です。contracts/*.solがないとcompileフェーズで失敗します。
README.mdがないとindex.htmlが生成されません。
package.jsonがない場合はどうなるのか試してません。
ドキュメントは次のコマンドでdocs/以下に生成されます。
node_modules/.bin/doxity build
ドキュメントをローカルで確認する
本来であれば、doxity developでローカルサーバが起動してそこでドキュメントを閲覧できるようになるはずなのですが、僕の環境ではうまく動きませんでした。（反応はするけどサーバがいつまでたっても起動しなかった)
直接gatsby developしてあげるとサーバが起動しました。gatsby developはscript/doxity/package.jsonにdevelopコマンドとして定義されてるので以下のようにscripts/doxity/に移動して実行してます。
cd scripts/doxity/ npm run develop
カスタマイズ
基本的に.doxityrcに設定を記述することでいろいろとカスタマイズが可能なようです。が、僕はそこまで触っていないので基本構造だけ説明します。詳しくは公式のREADME.mdを参照ください。
{
"target": "scripts/doxity",
"src": "contracts/*",
"dir": "pages/docs",
"source": "https://github.com/DigixGlobal/doxity-gatsby-starter-project/archive/a4886b7a7a04c018ac04fed3125d7d4785e74bed.tar.gz",
"out": "docs"
}上記がdoxity initで自動生成される.doxityrcの中身です。
上から順に説明すると
- target: doxityの作業ディレクトリの指定。ここを変更するとdoxity initで生成されるテンプレートフォルダの場所が変わる。doxity buildとかもこのディレクトリに対して実行される。
- src: ドキュメント生成の対象となるsolidityのソースファイルの指定。複数のソースを指定したい場合は"contracts/* contracts/token/*"みたいにスペースでつなげて指定する。
- dir: compileフェーズで生成されたcontractのjsonファイルの出力先？基本変更する必要はなさそう。いじったことがないので詳しくはわからない。
- source: doxity initした時にダウンロードしてくるドキュメントサイトのテンプレートファイルだと思う。
- out: 生成されたドキュメントの出力先。
以上です。
最後に
結構便利なツールなのですが、現状そのままでは動いてくれないので、自分で修正しようかなぁとは思ってるのですが、いかんせんjnode.jsにまだそこまで精通していないためどこを修正したらいいのかわかりません。
なので今後修正してくれる人が現れてくれることを期待して、修正すべきポイントをまとめておきます。
