Go: x/pkgsite: run locally to view documentation of a pending CL
With golang.org/x/tools/cmd/godoc, I can run a local documentation server from a GOPATH, and I can see rendered documentation for a change I'm working on. This is helpful if I'm writing non-trivial package documentation with multiple sections. I'd like to make sure the documentation looks the way I expect before mailing it for review.
I'd like to be able to run a local instance of pkgsite to accomplish the same task within a module.
jayconrod
All 9 comments
/cc @julieqiu per owners.
dmitshur
on 11 Jul 2020
@jayconrod x/tools/cmd/godoc has support for module mode (see https://groups.google.com/g/golang-dev/c/uxtj_w7wpnY/m/jR3ui47eBQAJ), what's the reason to want to use pkgsite instead of continuing to use godoc for viewing documentation locally?
dmitshur
on 11 Jul 2020
Just to give my personal opinion - if I'm used to the UI of pkg.go.dev, I would prefer to use the same UI when looking at documentation locally. The interface is easier to consume if one is used to it; it's harder to keep the buttons and features in one's muscle memory when jumping between godoc and pkgsite.
And this would also be useful when making small improvements or fixes to pkgsite, to allow quickly validating that the basic features and UI work as expected.
mvdan
on 12 Jul 2020
This came up in conversation with @julieqiu and her team last week. For me, it's firmly in the category of "nice to have, not urgent."
Does x/pkgsite use the same documentation rendering code as x/tools/cmd/godoc? I'm pretty sure they do, but if there's a chance they might diverge in the future, that would be a good reason to prefer x/pkgsite.
Aside from that, I'd mostly just prefer to use the same UI, as @mvdan mentioned.
jayconrod
on 13 Jul 2020
@julieqiu I would like to claim this if it's possible. I've been trying my hands at it for the last couple of days and hopefully will have a CL ready soon.
sudo-sturbia
on 6 Oct 2020
Please do, thanks @sudo-sturbia!
julieqiu
on 7 Oct 2020
Change https://golang.org/cl/260777 mentions this issue: internal/fetch: create FetchLocalModule
gopherbot
on 8 Oct 2020
Change https://golang.org/cl/260778 mentions this issue: internal/localdatasource: implement a local datasource
gopherbot
on 8 Oct 2020
Change https://golang.org/cl/260779 mentions this issue: cmd/frontend: add -local flag
gopherbot
on 8 Oct 2020
Related issues
rakyll
路
3Comments
lkarlslund
路
3Comments
natefinch
路
3Comments
michaelsafyan
路
3Comments
Miserlou
路
3Comments
Most helpful comment
Just to give my personal opinion - if I'm used to the UI of
pkg.go.dev, I would prefer to use the same UI when looking at documentation locally. The interface is easier to consume if one is used to it; it's harder to keep the buttons and features in one's muscle memory when jumping between godoc and pkgsite.And this would also be useful when making small improvements or fixes to pkgsite, to allow quickly validating that the basic features and UI work as expected.