提升Golang离线文档使用体验的方法

提升Golang离线文档使用体验的方法 我知道我们社区以GO工具链为傲。经过一些研究并与社区成员在线下和线上交流后，我意识到官方的 go doc 在离线文档导出方面可能有所欠缺。抱歉要与JavaDoc进行比较，但我需要一个基准。我理解GoDoc有一些其他工具没有的酷炫功能，但我只是实事求是地指出问题（请不要生气。我已经爱上GO了，并且希望它能变得更好）:)

以下是我提出此观点的理由，以及我为此所做的研究/依据。我也将此发布在社区中，因为这算是一个请求，我想知道除了我最初的发现之外，社区里有多少人会同意。

注意：请注意，使用 wget 是一种变通方法，而非解决方案；我读过鼓励这样做的帖子。如果我们作为一个社区对此感到满意，那么就不需要继续阅读了。但如果大多数人认为并非如此，请继续阅读。

要点

  1. 在线访问实时文档确实很酷；然而，我知道很多人是在离线模式下查阅文档的。也许实时方法适合CI/CD，但不适用于典型的产品交付场景。

  2. 我发现Go Doc中的自动链接功能无法正确解析我的注释。在这种情况下，我如何指定一个指向相对路径的链接？（本地主机、注解？）……抱歉，我不是在社区里问“如何”操作，而是想指出这种方式不够清晰。

  3. 模板化、CSS或SCSS定制。我一直以为我错了，这个功能肯定有，但我没有找到任何官方支持。我搜索的关键词是 Customize style "Godoc" 和 Customize CSS "Go doc"。虽然有一些结果，但没有出现标准的方法。这令人惊讶。 显而易见的建议：

    • 一个简单的标志，指定CSS文件路径，就可以将其包含在所有生成的页面中。假设标准文档使用了CSS选择器，这将是一个快速的改进。如果CSS路径是相对的，则文件会被包含在导出中；如果是绝对的，则无需包含。
    • 也可以为Logo等提供空白选择器。

依据

To generate Go-Doc offline it’s need some tricks to do.
Actually GoDoc can provide export as HTML file as well, but its will require some efforts, so to minimalize it I used web scrapper tools to get offline GoDoc.
Run it as usual then using web scrapper to capture all pages include all links have.
May this is not a best practice but will save more time to get the result.

更多关于提升Golang离线文档使用体验的方法的实战教程也可以访问 https://www.itying.com/category-94-b0.html

3 回复

rot13:

之前我与 Pandoc 的作者有过邮件交流。

谢谢！这很有用。

更多关于提升Golang离线文档使用体验的方法的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html


我也有同感。为了升级我的文档模块，我一直在研究一个Markdown生成器（无论是自己开发还是使用现有方案），已经有一段时间了。

你是否尝试过在本地服务器使用 Hugo 的同时，基于 https://github.com/robertkrimen/godocdown 进行扩展？

其中的源代码很可能包含你想要（也是我想要的，因为我已经解决了 Hugo 部分）的东西 😄。

Go语言的标准工具链确实提供了go doc命令用于查看文档，但离线文档生成确实存在一些限制。以下是针对你提到的问题的专业解决方案：

1. 离线文档生成方案

虽然go doc本身不直接生成HTML，但可以通过以下方式创建离线文档：

// 方案1：使用godoc工具（Go 1.12及之前版本包含）
// 安装godoc（如果尚未安装）
go install golang.org/x/tools/cmd/godoc@latest

// 启动本地文档服务器并导出
godoc -http=:6060 &
wget --mirror --convert-links --page-requisites --no-parent http://localhost:6060/pkg/

2. 使用pkg.go.dev离线模式

Go 1.16+ 提供了离线文档支持：

# 启用模块的离线模式
go env -w GOPROXY=direct
go env -w GOSUMDB=off

# 下载所有依赖的文档
go mod download

3. 自定义文档样式方案

虽然标准工具不直接支持CSS自定义，但可以通过以下方式实现：

// 方案1：使用自定义工具生成文档
package main

import (
    "golang.org/x/tools/godoc"
    "golang.org/x/tools/godoc/static"
    "html/template"
    "io"
    "os"
)

func generateCustomDoc() error {
    // 创建自定义模板
    tmpl := template.Must(template.New("").Parse(`
    <!DOCTYPE html>
    <html>
    <head>
        <link rel="stylesheet" href="custom.css">
        <style>
            {{.CustomCSS}}
        </style>
    </head>
    <body>
        {{.Content}}
    </body>
    </html>
    `))
    
    // 实现自定义文档生成逻辑
    // ... 
    return nil
}

4. 第三方工具方案

# 使用godox生成离线文档
go install github.com/cpuguy83/godox@latest
godox -output ./docs -include-subpackages ./...

# 使用pkgsite（pkg.go.dev的本地版本）
go install golang.org/x/pkgsite/cmd/pkgsite@latest
pkgsite -open=false &
wget -mkEpnp http://localhost:8080/

5. 相对链接处理示例

在注释中使用正确的链接格式：

// Package example demonstrates documentation features.
//
// See [SubPackage] for implementation details.
// Relative link: ./subpackage/
// Absolute link: https://pkg.go.dev/example.com/pkg

// SubPackage provides additional functionality.
package subpackage

// Function demonstrates link resolution.
// Reference: [example.Function]
func Function() {}

6. 完整的离线文档生成脚本

#!/bin/bash
# generate-offline-docs.sh

PORT=6060
OUTPUT_DIR="./go-offline-docs"

# 启动godoc服务器
godoc -http=:$PORT &
PID=$!

# 等待服务器启动
sleep 2

# 镜像整个文档站点
wget \
    --mirror \
    --convert-links \
    --page-requisites \
    --no-parent \
    --directory-prefix="$OUTPUT_DIR" \
    "http://localhost:$PORT/pkg/"

# 停止服务器
kill $PID

# 添加自定义样式
cat > "$OUTPUT_DIR/custom.css" << 'EOF'
/* 自定义文档样式 */
body { font-family: 'Segoe UI', sans-serif; }
pre { background: #f5f5f5; padding: 1em; }
.permalink { color: #007d9c; }
EOF

这些方案提供了从基础到高级的离线文档处理方式，可以根据具体需求选择适合的方法。Go社区也在不断改进文档工具，后续版本可能会有更完善的官方支持。

回到顶部