Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: run locally to view documentation of a pending CL #40159

Open
jayconrod opened this issue Jul 10, 2020 · 4 comments
Open

x/pkgsite: run locally to view documentation of a pending CL #40159

jayconrod opened this issue Jul 10, 2020 · 4 comments

Comments

@jayconrod
Copy link
Contributor

@jayconrod jayconrod commented Jul 10, 2020

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.

@dmitshur
Copy link
Member

@dmitshur dmitshur commented Jul 11, 2020

/cc @julieqiu per owners.

@dmitshur
Copy link
Member

@dmitshur dmitshur commented Jul 11, 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 dmitshur removed the Documentation label Jul 11, 2020
@mvdan
Copy link
Member

@mvdan mvdan commented Jul 12, 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.

@julieqiu julieqiu added the pkgsite label Jul 12, 2020
@jayconrod
Copy link
Contributor Author

@jayconrod jayconrod commented Jul 13, 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.

@julieqiu julieqiu mentioned this issue Jul 23, 2020
0 of 1 task complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.