我想要为公司内部的Go Package在GoDoc中输出静态HTML

2 年 ago

科, 雅

2 minutes

首先

这篇文章是基于一个想法：“我想让公司内部管理的Go包的GoDoc可以让任何人都能浏览到。”

在Wantedly公司，我们通过在Kubernetes上运行GoDoc服务器（gddo-server）来搭建公司内部的GoDoc环境，就像这篇文章中所介绍的那样。

这次我们采取了一个与之前不同的方法，通过在CI上生成静态的HTML并将其托管在S3上，这样就可以在没有专门的服务器的情况下运行我们内部的GoDoc系统。

环境和版本

前进：go的版本为go1.13.4 darwin/amd64
GoDoc(golang.org/x/tools/cmd/godoc)的版本为v0.0.0 (4b814e0)

做过的事情。”

使用CI工具根据GoDoc生成HTML，并将其上传到公司内部的Amazon S3。

在取得了CI上的godoc命令后，我希望能直接使用godoc获取静态HTML。然而，根据当前的godoc版本（截至2020年4月30日），在下面的问题页面上我了解到，并不存在生成静态HTML的选项。

阅读这个问题页面后，有记录说明如果使用wget工具，则可以解决问题。

https://github.com/golang/go/issues/2381#issuecomment-66059484

由于测试结果表明它确实能够正确生成HTML，因此我会将其嵌入到CI脚本中。

在下面的例子中，从GitLab CI的Yaml文件中提取出来的部分，但是如果是在Linux的CI环境中，Shell部分应该可以以相同的方式工作。

  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。

请参考

https://qiita.com/somat/items/b775f7e082f1559707e2