在本地構建你的 Golang 包文檔
編寫 Golang 文檔
最近我專注於 eBPF，需要寫比以前更多的東西。這也意味着要爲各種生態系統撰寫文檔。雖然某些工具在作者完成工作時產生阻力，但本文介紹我目前爲編寫 Golang 文檔而設置的工作流程。
godoc 已被棄用
與我的 Rust 設置類似，我想在發佈之前本地查看我的模塊文檔在 pkg.go.dev 上的呈現方式。這是可能的，但自那時起 godoc 就已被棄用，沒有官方解決方案。
現在的建議是指導用戶使用 pkgsite（用於渲染 pkg.go.dev 的工具），但確切的設置方式留給用戶來練習。
那我們開始練習吧。
pkgsite 命令
golang/pkgsite hosts the cli pkg.go.dev uses for docs rendering. The comments of the pkgsite cmd are concise but can get us started:
golang/pkgsite 託管了用於渲染文檔的 pkg.go.dev 命令行界面。 pkgsite 命令的註釋雖然簡潔，但可以讓我們開始：
// Pkgsite 提取和生成 Go 程序的文檔。
// 它作爲 Web 服務器運行，將文檔呈現爲 Web 頁面。
//
// 要安裝，請從 pkgsite 存儲庫根目錄運行 `go install ./cmd/pkgsite`。我們將使用它來設置一個本地服務器版本的 pkg.go.dev，其中包含 Golang 包的文檔渲染功能。所以讓我們安裝它。我在其他地方看到的建議是本地克隆此存儲庫，構建它並將其安裝在 $PATH 中的某個位置，但這個 go install 應該就可以工作：
$ go install golang.org/x/pkgsite/cmd/pkgsite@latest一旦安裝完成，只需將其運行在我們的 Go 包倉庫所在的位置即可：
$ cd /path/to/go/pkg
$ pkgsite
2022/06/16 10:13:55 Info: Listening on addr http://localhost:8080你可以使用 -http localhost:3030 自定義綁定端口。
打開本地站點將顯示一個類似於 pkg.go.dev 的頁面，包含搜索欄和其他內容。當然，如果你進行搜索，你不會看到任何包，因爲我們只渲染了本地包（雖然有一些參數可以更改這個行爲）。
你的本地文檔
現在，類似於 pkg.go.dev，你可以通過將 go.mod 中的模塊路徑附加到 URL 上來檢查本地模塊的文檔：
http://localhost:8080/my/local/module/path就是這樣。現在你可以以 Web 形式查看你編寫的模塊文檔了。只需安裝 pkgsite，你就可以在發佈之前預覽 Go 項目的文檔長什麼樣了。
但是，我們能不能進一步推動它呢？我不想手動保存文件，在思考之間殺死服務器，再重新啓動服務器並刷新頁面。我希望只需打開一個瀏覽器標籤即可在我的文本編輯器中輸入時渲染頁面。
熱加載
爲此，我們需要更多的工具。一個用於監視我們的 Go 文件何時發生更改，另一個用於與我們的瀏覽器通信何時重新加載頁面。理想情況下，這應該是一個_單獨的_工具來完成（也許有一天 pkgsite 會內置這個功能...）。如果你來自前端 JavaScript 的世界，這是基本操作，通常會伴隨着框架的工具。現在我們要開始工作了。
我選擇的文件監視工具是 nodemon。它的工作表現很好，並且在需要時可以配置它（我們將需要這樣做）。起初，我想找一個基於 Go 的文件監視器，但我找不到任何一個能滿足我的需求。我甚至嘗試將 cosmtrek/air 強行塞進這個角色，但沒有成功。
現在我們有了一個文件監視器，我們希望告訴瀏覽器何時重新加載頁面。我們將使用 browser-sync 來實現這一點。
終端命令
以下是我們將使用的關鍵命令。爲每個進程打開一個新終端，或者只是將其中一個放在後臺：
$ browser-sync start --proxy "localhost:8080"
[Browsersync] Proxying: http://localhost:8080
[Browsersync] Access URLs:
--------------------------------------
Local: http://localhost:3000
External: http://192.168.1.227:3000
--------------------------------------
UI: http://localhost:3001
UI External: http://localhost:3001
--------------------------------------我們需要設置這個代理的原因是，我們需要一種自動通知瀏覽器某些東西已經改變的方式。爲此，browser-sync 在我們的請求中注入了一小段 JavaScript 代碼，它會監聽一個信號以確定何時重新加載。
$ nodemon --signal SIGTERM --watch my-mod.go --exec "browser-sync reload && pkgsite ."
[nodemon] 2.0.16
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): my-mod.go
[nodemon] starting `browser-sync reload && pkgsite .`這就是我們創建該信號的方式。nodemon 監視 my-mod.go 的文件更改，並自動重新啓動 pkgsite 進程，同時向 browser-sync 發送信號。
總結
當這兩個工具並行運行時，你現在應該具備了自動化的文檔重載功能。我現在可以在我的文本編輯器中編寫 go doc 註釋，保存文件並查看選項卡重新加載。
現在沒有藉口不寫註釋了，但開發體驗仍可以更好。顯然除了設置這個痛苦之外，重新加載的速度也比必要的慢。我們不應該等待整個進程啓動，然後再等待它渲染我的本地模塊，才能在瀏覽器標籤中看到它。
也許當你閱讀這篇文章時，那個 pkgsite 問題 已經解決了，並且會存在更多針對文檔的工具。或者也許我會有一個空閒的週末，可以發送一些 PR。
原文地址： https://mdaverde.com/posts/golang-local-docs/
原文作者：Milan
本文永久鏈接：
https://github.com/gocn/translator/blob/master/2023/w22_Build_your_Golang_package_docs_locally.md
譯者： 朱亞光
校對： 吳雨浩
本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/WPj9pPcW_O3VJpGmvOvgoQ