godoc を静的ファイルに変換して、GitHub Pages にデプロイする
概要
社内リポジトリで、godoc を生成して、GitHub Pages にデプロイする機会があったので、まとめます。本記事では GitHub Actions を利用しますが、スクリプトを移植すれば、ほかの CI ツールでも利用できます。
作成したサンプルコードは以下になります。
本書のサンプルコードに従って godoc を生成すると、下記のような GitHub Pages が生成されます。
TL;DR
GitHub Actions で実行する場合は、下記のファイルを利用すれば完了です。
name: generate-godoc-deploy-gh-pages
on:
push:
branches:
- 'main'
jobs:
generate-godoc-deploy-gh-pages:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Set up Go
uses: actions/setup-go@v4
with:
go-version: 1.18
- name: Set git config
run: |
git config --global user.name github-actions[bot]
git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com
- name: Generate godoc
run: |
git fetch origin
git switch gh-pages || git switch -c gh-pages
git merge main
rm -rf localhost:8888 docs
go install golang.org/x/tools/cmd/godoc@latest
$(go env GOPATH)/bin/godoc -http=localhost:8888 & \
sleep 30
wget -r -np -nv -N -E -p -k -e robots=off --reject-regex="png" "http://localhost:8888/pkg/github.com/Msksgm/generate-static-godoc-and-deploy-github-pages-sample/"
pkill godoc
mv localhost:8888/ docs/
- name: Push docs to gh-pages
run: |
git add docs \
&& git diff --cached --quiet \
|| (git commit -m "docs: godoc を更新" && git push origin gh-pages)
Generate godoc において gh-pages ブランチ上で godoc を生成します。また、Push docs to gh-pages で差分があった場合 push します。godoc の生成から gh-pages に push する箇所と、GitHub Actions の箇所をそれぞれ解説します。
解説
godoc の生成から gh-pages に push
godoc の生成は、generate-godoc-deploy-gh-pages.yml の下記の部分が該当します。Generate godoc ステップが godoc の生成、Push docs to gh-pages が docs に差分があった場合に push するスクリプトです。スクリプト部分を理解できれば、GitHub Actions 以外の CI ツールにも移植可能です。順番を追って詳細に説明します。
jobs:
generate-godoc-deploy-gh-pages:
# 略
steps:
# 略
- name: Generate godoc
run: |
git fetch origin
git switch gh-pages || git switch -c gh-pages
git merge main
rm -rf localhost:8888 docs
go install golang.org/x/tools/cmd/godoc@latest
$(go env GOPATH)/bin/godoc -http=localhost:8888 & \
sleep 30
wget -r -np -nv -N -E -p -k -e robots=off --reject-regex="png" "http://localhost:8888/pkg/github.com/Msksgm/generate-static-godoc-and-deploy-github-pages-sample/"
pkill godoc
mv localhost:8888/ docs/
- name: Push docs to gh-pages
run: |
git add docs \
&& git diff --cached --quiet \
|| (git commit -m "docs: godoc を更新" && git push origin gh-pages)
godoc の生成
下記のスクリプトは、ホスティングされている godoc を静的ファイルに変換して、docs ディレクトリに保存するスクリプトです。保存されるファイルのパスはdocs/pkg/github.com/Msksgm/generate-static-godoc-and-deploy-github-pages-sample/です。
git fetch origin
git switch gh-pages || git switch -c gh-pages
git merge main
rm -rf localhost:8888 docs
go install golang.org/x/tools/cmd/godoc@latest
$(go env GOPATH)/bin/godoc -http=localhost:8888 & \
sleep 30
wget -r -np -nv -N -E -p -k -e robots=off --reject-regex="png" "http://localhost:8888/pkg/github.com/Msksgm/generate-static-godoc-and-deploy-github-pages-sample/"
pkill godoc
mv localhost:8888/ docs/
それぞれの解説は下表の通りです。
| コマンド | 解説 |
|---|---|
git fetch origin |
origin から最新の変更を取得 |
git switch gh-pages | | git switch -c gh-pages
|
gh-pages があれば switch なければ作成 |
git merge main |
main ブランチの変更を取り込み |
rm -rf localhost:8888 docs |
後述の wget で godoc を localhost:8888 と docs に保存するため、ローカルの localhost:8888 と docs を削除 |
go install golang.org/x/tools/cmd/godoc@latest |
godoc を install |
$(go env GOPATH)/bin/godoc -http=localhost:8888 & \ sleep 30
|
godoc を起動する。完全に起動する前に wget しないように 30 秒 sleep させる |
wget -r -np -nv -N -E -p -k -e robots=off --reject-regex="png" "http://localhost:8888/pkg/github.com/Msksgm/generate-static-godoc-and-deploy-github-pages-sample/" |
godoc を静的な HTML に変換してダウンロードする。詳細は後述 |
pkill godoc |
godoc を終了させる |
mv localhost:8888/ docs/ |
localhost:8888 ディレクトリを docs ディレクトリに名前を変更 |
注意点は、wget を利用する際の下記の 2 つです。
- localhost:8888 という名前のディレクトリに保存される
-
http://localhost:8888を指定すると、プロジェクト以外の godoc（ライブラリなど）もダウンロードされるので、pkg 以下を明示的に指定する
docs に差分があった場合に push
git add して、ステージングエリアの diff があった場合、push します。
git diff --cached --quiet は差分がある場合、ステータスコード 0 なければステータスコード 1 を返します。
git add docs \
&& git diff --cached --quiet \
|| (git commit -m "docs: godoc を更新" && git push origin gh-pages)
GitHub Actions の設定
GitHub Actions の設定箇所は下記になります。
jobs:
generate-godoc-deploy-gh-pages:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Set up Go
uses: actions/setup-go@v4
with:
go-version: 1.18
- name: Set git config
run: |
git config --global user.name github-actions[bot]
git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com
注意点は下記の 3 つです。
| 注意点 | 理由 |
|---|---|
permissions に contents: write を指定する |
指定しないと権限エラーが発生します。リポジトリ全体で write 権限を与えることもできますが、権限が理解しづらくなるので yaml ファイルに記載します。 |
actions/checkout@v3 ではオプションに fetch-depth: 0を指定する |
checkout action はデフォルトだと shallow で checkout するので、Git の commit や push などをしようとすると、異なる歴史として扱われます。そのため、fetch-depth: 0 によって通常の checkout と同様の操作にします。 |
| Git の user.name と user.emal には GitHub Actions の bot を指定する | 完全に好みですが、bot にコミットや push されたことを明示するために、今回の設定にしました。指定方法はほかにもあるのでプロジェクトに合わせて指定してください。 |
補足
GitHub Actions 以外で GitHub Pages の説明を補足します。
GitHub Pages を設定する
GitHub Pages の設定方法を解説します。
「Settings」->「Pages」を開き、「Branch」で gh-pages と/docs を指定して、「Save」を押下することで反映されます。
これで、gh-pages ブランチの docs ディレクトリが GitHub Pages にホスティングされました。
GitHub Pages の設定
少し待ちページを再読み込みすると、下記のようにホスティングされます。
ホスティングされた後の GitHub Pages
GitHub Pages を確認
上述した解説からどのような godoc が生成されるの確認します。本記事のサンプルコードでは下記のソースコードを記述していました。docs.go は package レベルの godoc を記述する際に利用するファイルです。
// Package greet 挨拶する機能をまとめる
package greet
package greet
import "fmt"
// Greet は引数に対して挨拶する関数
func Greet(name string) string {
return fmt.Sprintf("Hello %s !", name)
}
それでは、下記のリンクを開いてみましょう。
下記のように、コードコメントが godoc に反映されていることがわかります。
godoc 01
godoc 02
まとめ
本記事では、GitHub Actions で静的に生成した godoc を GitHub Pages にデプロイする方法を説明しました。スクリプトを移植すれば、ほかの CI ツールでも利用可能ですので、試してみてください。注意点としては、社内リポジトリを対象にしていることにご留意ください。
参考
スクリプトは以下の記事を参考にしました。
GitHub Actions がデプロイしたように見せる設定は以下を難航にしました。
Discussion