Skip to content

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

New issue

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

#

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

Already on GitHub? # to your account

Jump to bottom
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
Labels
FeatureRequest Issues asking for a new feature that does not need a proposal. FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Milestone
pkgsite/unplanned

Comments

@jayconrod
Copy link
Contributor

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 jayconrod added this to the Unreleased milestone Jul 10, 2020
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Jul 10, 2020
@dmitshur dmitshur added FeatureRequest Issues asking for a new feature that does not need a proposal. NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. and removed Documentation Issues describing a change to documentation. labels Jul 11, 2020
@dmitshur
Copy link
Contributor

/cc @julieqiu per owners.

@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Jul 11, 2020
@dmitshur
Copy link
Contributor

@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 Issues describing a change to documentation. label Jul 11, 2020
@mvdan
Copy link
Member

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.

@jayconrod
Copy link
Contributor Author

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
Open
6 tasks
@sudo-sturbia
Copy link

@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
Member

julieqiu commented Oct 6, 2020

Please do, thanks @sudo-sturbia!

@gopherbot
Copy link
Contributor

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

@gopherbot
Copy link
Contributor

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

@gopherbot
Copy link
Contributor

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
@sudo-sturbia @julieqiu
internal/fetch: create FetchLocalModule
0077d00 
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
@sudo-sturbia @julieqiu
internal/localdatasource: implement a local datasource
082bca2 
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>
@golang golang locked and limited conversation to collaborators Oct 16, 2021
# for free to subscribe to this conversation on GitHub. Already have an account? #.
Assignees
No one assigned
Labels
FeatureRequest Issues asking for a new feature that does not need a proposal. FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Projects
None yet
Milestone
pkgsite/unplanned
Development

No branches or pull requests
6 participants
@jayconrod @dmitshur @mvdan @julieqiu @gopherbot @sudo-sturbia