※こちらは，会社の技術ブログとのクロスポスト記事です．元の記事はこちら
業務でプログラムのドキュメント資料が必要になることがあります．
面倒な資料作成は，なるべく効率的に終わらわせたいですよね．
この記事では，Go言語プログラムの資料を自動生成する方法を紹介します．
前提
今回は例として，Ginというウェブフレームワークの資料を自動生成したいと思います．
目標は，docsディレクトリに資料を用意することです．最初に環境を用意します．
$ git clone https://github.com/gin-gonic/gin.git
$ go install github.com/gin-gonic/gin@latest
$ cd gin/
$ echo */ # ディレクトリ確認
binding/ docs/ examples/ ginS/ internal/ render/ testdata/
資料の生成にgodoc，資料の保存にwgetを使います．
コマンドが通っていることを確認してください．
準備と実行
まず，スクリプトファイルdoc_generator.shを作成します．
#!/bin/bash
godoc -http=:6060 & # バックグラウンド実行
RUNNING_PID=$! # godocのPIDを取得
sleep 1 # godocの実行を1秒待機
wget -np -k -p -q -r -E http://localhost:6060/pkg/github.com/gin-gonic/gin/?m=all
kill ${RUNNING_PID} # godocの実行を終了
find localhost+6060 -name "index.html" -delete
mv -f localhost+6060 docs/localhost+6060
次に，資料へ遷移するhtmlファイルdocs/document.htmlを作成します．
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="0;
URL=localhost+6060/pkg/github.com/gin-gonic/gin/index.html@m=all.html">
</head>
</html>
以上で準備は完了です．プログラムを実行して資料を確認しましょう．
$ ./doc_generator.sh # シェルスクリプト実行
$ start docs/document.html # ウェブブラウザで閲覧
ウェブブラウザで上の画面が表示されたら，資料の自動生成は成功です．
解説
godocは，Go言語プログラムの資料を自動生成する便利ツールです．
実行するとlocalhost:6060が起動します．
（httpの指定がない場合もlocalhost:6060が起動します）
作業のゴールは，localhost:6060起動中のみ閲覧できる資料を手元に保存することです．
通常godocでは，先頭が小文字のprivate関数とinternalディレクトリ配下のプログラムが見れません．
URLの末尾に?m=allと記述し，queryを追加するとプログラムが表示されるようになります．
左側はqueryなし，右側は?m=allqueryありの資料です．
上は表示関数を比較した図，下は表示ディレクトリを比較した図です．
doc_generator.shでは，最初にgodocをバックグラウンドで実行し，wgetで資料をファイルとして手元に保存します．
そして，バックグラウンドで実行しているgodocを終了します．
次に，今回はquery?m=allを指定した資料が欲しいので，queryがない資料を削除します．
最後に，保存した資料をdocsディレクトリ配下に移動します．
wgetのオプションの意味は，以下の通りです．
- np, no-parent: 親ディレクトリを無視する．情報を取得しない．
- k, convert-links: ローカルでの参照を有効にする．リンクを書き換える．
- p, page-requisites: HTML表示に必要な画像，CSS，JavaScript等も取得する．
- q, quiet: 途中経過等を何も出力しない.
- r, recursive: 再帰的にダウンロードする．
- E, html-extension: HTML形式のファイル末尾に.htmlを追加する．
終わりに
Go言語プログラムの資料を自動生成する方法を紹介しました．
便利なgodocを積極的に活用していきましょう．