はじめに

「社内で管理しているGoのパッケージのGoDocを誰でも閲覧できるようにしたい」というモチベーションによる記事です。

Wantedlyさんではこちらの記事のようにKubernetesでGoDocサーバ(gddo-server)を走らせることで社内GoDoc環境を構築しています。

今回はこのアプローチではなく、静的なHTMLをCI上で生成しそれをS3にホスティングすることで特にサーバを持たずに社内GoDocを運用する方針にしました。

環境・バージョン

Go: go version go1.13.4 darwin/amd64
GoDoc(golang.org/x/tools/cmd/godoc): v0.0.0 (4b814e0)

やったこと

CIでGoDocを元にHTMLを生成しそれを社内Amazon S3へアップロードします。

CI上でgodoc(golang.org/x/tools/cmd/godoc)のコマンドを取得した後、素直にgodocで静的HTMLを取得したかったのですが、現状(2020年4月30日時点)のgodocのバージョンにおいては、静的なHTMLを生成するオプション等は存在しないと下記のIssueページで知りました。

このIssueページを読むと、wgetを使えばなんとか対応できるとの記載がありました。

試したらたしかにちゃんとHTMLを生成してくれたので、CIのスクリプトに組み込みます。

下記の例ではGitLab CIのYamlファイルからの抜粋ですが、シェルな部分はLinuxなCI環境なら同じように動くはずです。

.gitlab-ci.ymlの抜粋

  stage: generate-godoc-html
  variables:
    ARTIFACTS_DIR: artifacts
    GODOC_OUT: godoc
    GODOC_SERVER: localhost:6060
  script:
    - godoc -http=${GODOC_SERVER} & # バックグラウンド実行
    - sleep 1 # 一応1秒寝かす
    # ↓wgetでHTMLを生成する
    - wget -r -np -N -E -k http://${GODOC_SERVER}/pkg/【対象パッケージのPath】
    # ↓(あってもなくてもホスティング先で表示はされる)HTML内の"localhost:6060"なPathをホスティング先のものに置換してやる
    - find ./${GODOC_SERVER}/ -name "*.html" -print0 | xargs -0 sed -i -e "s/http:\/\/${GODOC_SERVER}\/src\/【対象パッケージのPath】/https:\/\/【GitレポジトリのPath】"
    - find ./${GODOC_SERVER}/ -name "*.html" -print0 | xargs -0 sed -i -e "s/http:\/\/${GODOC_SERVER}/https:\/\/【S3のPath】\/${GODOC_OUT}\/master/"
    # ↓生成したHTMLらを移動
    - mkdir -p ${ARTIFACTS_DIR}/${CI_PIPELINE_ID}/${GODOC_OUT}
    - mv ${GODOC_SERVER}/* ${ARTIFACTS_DIR}/${CI_PIPELINE_ID}/${GODOC_OUT}
  artifacts:
    paths:
      - ${ARTIFACTS_DIR}/${CI_PIPELINE_ID}/${GODOC_OUT} # 保存
    expire_in: 3 days

  stage: upload-to-s3
  script:
    - aws s3 cp ${ARTIFACTS_DIR}/${CI_PIPELINE_ID}/${GODOC_OUT} 【対象S3バケットのPath】 --recursive

上記wgetのオプションのクセが強いので解説です。

-r : 再帰的にダウンロードする
-np : 親ディレクトリを見ない
-N : ローカルより新しいものでない限りファイルを取得しない
-E : 拡張子.htmlをhtmlファイルに追加 (拡張子がない場合)
-k : リンクを相対リンクに変換

また、HTML内のリンクの整合を取るために上記のように、sedコマンドでlocalhost:6060な部分を置換しています。これにより、GoDoc内のリンクやソースコード先に問題なく飛ぶことができます。詳細を把握するためにはローカル環境で検証することをおすすめします。

これが走った後、対象のS3ホスティングのURLにアクセスすると、以下のようにGoDocを見ることができました。

社内Go PackageのためにGoDocで静的なHTMLを出力したい

はじめに

環境・バージョン

やったこと

参考