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

Closed
jayconrod opened this issue Jul 10, 2020 · 9 comments
Closed

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

jayconrod opened this issue Jul 10, 2020 · 9 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.

@sudo-sturbia
Copy link

@sudo-sturbia sudo-sturbia commented Oct 6, 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.

@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Oct 6, 2020

Please do, thanks @sudo-sturbia!

@gopherbot
Copy link

@gopherbot gopherbot commented Oct 8, 2020

Change https://golang.org/cl/260777 mentions this issue: internal/fetch: create FetchLocalModule

@gopherbot
Copy link

@gopherbot gopherbot commented Oct 8, 2020

Change https://golang.org/cl/260778 mentions this issue: internal/localdatasource: implement a local datasource

@gopherbot
Copy link

@gopherbot gopherbot commented Oct 8, 2020

Change https://golang.org/cl/260779 mentions this issue: cmd/frontend: add -local flag

gopherbot pushed a commit to golang/pkgsite that referenced this issue Oct 16, 2020
Create FetchLocalModule to fetch modules from local directories without
needing a proxy instance.

Add tests for FetchLocalModule and update helper functions.

Updates golang/go#40159

Change-Id: Ie1296e6a2008bf8d7c3811864d5d948e042fcb38
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/260777
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Julie Qiu <julie@golang.org>
Trust: Jonathan Amsterdam <jba@google.com>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
gopherbot pushed a commit to golang/pkgsite that referenced this issue Oct 16, 2020
Create localdatasource package which implements an in-memory
internal.DataSource to display documentation locally.

Add tests for localdatasource.DataSource.

Updates golang/go#40159

Change-Id: Ie18dd68e6108cfa361c4db31030679fc55661d35
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/260778
Trust: Jonathan Amsterdam <jba@google.com>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Julie Qiu <julie@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
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
6 participants