如何通过godoc为文件夹内所有包生成关联的HTML文档？

好问题！虽然godoc -html默认只能为单个包生成独立的HTML文档，但我们可以通过两种实用方法，生成和godoc -http模式一样的、相互关联的全项目HTML文档集合，方便交付给他人浏览。

方法一：用godoc HTTP服务 + 静态站点镜像工具（推荐） #

这是最省心的方式，利用godoc启动的本地HTTP服务，再用镜像工具把整个文档站点下载成静态HTML文件，所有链接都会自动处理成可本地访问的相对路径：

1. 先启动godoc的HTTP服务，指定一个端口（比如6060）：

   godoc -http=:6060
   

2. 打开另一个终端，用wget（或者curl的递归下载功能）镜像整个项目的文档页面：

   wget --mirror --convert-links --adjust-extension --page-requisites --no-parent http://localhost:6060/pkg/your-project-module-path/
   

   这里的参数解释：

   • --mirror：开启镜像模式，递归下载所有关联页面
   • --convert-links：把页面里的绝对链接转换成相对链接，确保本地打开时能正常跳转
   • --adjust-extension：给HTML文件加上.html后缀，方便本地直接打开
   • --page-requisites：下载页面依赖的所有资源（比如CSS、JS），保证样式和交互正常
   • --no-parent：只下载指定路径下的内容，不会爬到godoc的其他系统包文档

3. 下载完成后，你会得到一个和原站点结构一致的静态文件目录，直接打开其中的index.html就能像在浏览器里用godoc -http一样浏览所有包的关联文档了。

方法二：遍历包生成HTML并手动修正链接（适合自定义需求） #

如果需要更精细的控制，可以写脚本遍历项目里的每个包，用godoc -html逐个生成HTML，再批量替换里面的链接为相对路径：

1. 写一个简单的shell脚本（比如generate-docs.sh）遍历所有包：

   #!/bin/bash
   DOC_DIR="./godoc-docs"
   mkdir -p "$DOC_DIR"
   
   # 遍历项目下的所有Go包（排除vendor等目录）
   find . -type f -name "*.go" | grep -v vendor | xargs dirname | sort | uniq | while read -r pkg; do
       # 生成对应包的HTML文件，路径和包结构对应
       OUT_FILE="$DOC_DIR/${pkg#./}.html"
       mkdir -p "$(dirname "$OUT_FILE")"
       godoc -html "$pkg" > "$OUT_FILE"
   done
   

2. 批量替换HTML里的绝对链接：比如把http://localhost:6060/pkg/your-project/开头的链接，替换成相对路径的.html文件。可以用sed命令来批量处理：

   sed -i 's|http://localhost:6060/pkg/your-project/\(.*\)|./\1.html|g' "$DOC_DIR"/*.html
   

   注意要根据你的项目路径调整匹配规则，确保所有包之间的跳转链接都能正确指向生成的HTML文件。

注意事项 #

• 如果你的项目使用Go Modules，确保运行godoc时处于项目根目录，并且GO111MODULE=on（默认开启），这样godoc才能正确识别模块下的所有包。
• 生成的静态文档目录可以直接和项目代码打包交付，接收方不需要安装Go或godoc，直接用浏览器打开就能浏览。

内容的提问来源于stack exchange，提问作者Ali Dabour