Proposal Details
Currently, go doc -http serves local HTML documentation using a fixed, hardcoded version of pkgsite
(golang.org/x/pkgsite/cmd/internal/doc). This proposal adds a -doctool flag to go doc allowing users to specify a custom local documentation server binary or dynamically fetch a different pkgsite version.
go doc -http -doctool <spec> ...
Background
When previewing docs with go doc -http, developers and tooling authors often need to:
- Test against newer or older versions of pkgsite (e.g.,
@latest or @v1.2.3).
- Serve docs using the local build of pkgsite (for testing or bug fix) or company-internal documentation rendering servers.
Other go commands already support tool-override flags using a pattern, such as go vet -vettool=prog and go fix -fixtool=prog.
Spec
This flag is used only with -http. The flag accepts two types of arguments:
-
Alternative version or package (@version or <modulepath>@version):
Shorthands like @latest, v1.2.3, latest, or explicit module paths (e.g., example.com/mypkgsite@v1.0.0). go doc dynamically builds and runs the specified package.
-
Local binary:
A local file path or binary name (e.g., -doctool=./mydoc or -doctool=$(which customdoc)). Following the exact same logic as -vettool and -fixtool, the path is resolved using filepath.Abs before any -C directory changes and validated prior to execution.
Compatibility
This change is fully backwards compatible. If -doctool is omitted, go doc -http continues using the default built-in pkgsite version.
Proposal Details
Currently,
go doc -httpserves local HTML documentation using a fixed, hardcoded version of pkgsite(golang.org/x/pkgsite/cmd/internal/doc). This proposal adds a
-doctoolflag togo docallowing users to specify a custom local documentation server binary or dynamically fetch a different pkgsite version.Background
When previewing docs with
go doc -http, developers and tooling authors often need to:@latestor@v1.2.3).Other
gocommands already support tool-override flags using a pattern, such asgo vet -vettool=progandgo fix -fixtool=prog.Spec
This flag is used only with
-http. The flag accepts two types of arguments:Alternative version or package (
@versionor<modulepath>@version):Shorthands like
@latest,v1.2.3,latest, or explicit module paths (e.g.,example.com/mypkgsite@v1.0.0).go docdynamically builds and runs the specified package.Local binary:
A local file path or binary name (e.g.,
-doctool=./mydocor-doctool=$(which customdoc)). Following the exact same logic as-vettooland-fixtool, the path is resolved usingfilepath.Absbefore any-Cdirectory changes and validated prior to execution.Compatibility
This change is fully backwards compatible. If
-doctoolis omitted,go doc -httpcontinues using the default built-in pkgsite version.