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/tools/cmd/godoc, gddo: module support #26827

Open
agnivade opened this Issue Aug 6, 2018 · 8 comments

Comments

Projects
None yet
10 participants
@agnivade
Member

agnivade commented Aug 6, 2018

I wanted to open an umbrella issue discussing the changes that we might need to do to adapt godoc now that we will start to have modules.

  • For starters, now that we have $GOPATH/src/mod folder containing versioned snapshots of various libraries, all of them show up in the /pkg/ html output.

mod

What is the recommendation to handle this case ? To simply dump all versions of all packages does not seem like the right thing to do. It also gives a sense of exposing internal details of storing "@vX.Y.Z" along with folder names.

(This is taken care of by moving from src/mod to pkg/mod)

  • Also, for new systems that are completely working outside of GOPATH, how do we decide what to show in the output of /pkg/ page ? In the current workflow, it won't show anything because $GOPATH/src is empty. Everything is inside $GOPATH/pkg/mod.

Can we improve this ? Should we add an option to show godoc for a specific module root ? Or some notion to show documentation of only a given package.

I have not been following the progress on modules. So please let me know if there are some obvious fixes to these.

@rsc @bradfitz

@gopherbot gopherbot added this to the Unreleased milestone Aug 6, 2018

@kr

This comment has been minimized.

Contributor

kr commented Aug 6, 2018

@agnivade note that in b8f42d7, the module cache moved to $GOPATH/pkg/mod, so this particular "for starters" issue seems like it's been addressed. If you still have anything in $GOPATH/src/mod, you can delete it.

@agnivade

This comment has been minimized.

Member

agnivade commented Aug 7, 2018

Indeed. Thank you.

@thepudds

This comment has been minimized.

thepudds commented Aug 8, 2018

@gopherbot please add modules label

@gopherbot gopherbot added the modules label Aug 8, 2018

@agnivade

This comment has been minimized.

Member

agnivade commented Aug 8, 2018

I don't think this is a modules issue. It is about changes in godoc due to modules.

@agnivade agnivade removed the modules label Aug 11, 2018

@dmitshur dmitshur changed the title from x/tools/cmd/godoc: improvements to adapt to module aware repo structure to x/tools/cmd/godoc, gddo: module support Oct 11, 2018

@acln0

This comment has been minimized.

Contributor

acln0 commented Oct 12, 2018

I have been directed here from the #modules channel on the Gophers slack. Hopefully this is the right place to give a report.

I'm writing a new package using modules, outside GOPATH. I have not pushed this package anywhere public just yet. I'd like to know how the HTML documentation renders before I do. I am writing examples and adding code blocks to godoc comments as well, so doing go doc acln.ro/foo is not enough.

So far, I've written a little shell script that copies the entire tree to GOPATH so that godoc can pick it up. As I iterate, I run the shell script. This doesn't feel quite right. I have also tried using symlinks, which godoc (rightfully) ignores.

Should we add an option to show godoc for a specific module root ?

That would certainly be nice. I would like to be able to point godoc at some directory outside GOPATH, where I am currently working.

@go101

This comment has been minimized.

go101 commented Nov 12, 2018

[moved from https://github.com//issues/28720]

A suggestion: the godoc.org page for a package containing the go.mod file should also show an import/replace path specified in the go.mod file.

For example, this package https://godoc.org/github.com/go101/tinyrouter specified its import path in go.mod as go101.org/tinyrouter instead of its hosing path. The the doc page should also list the import path which is specified in go.mod.

It would be better if the doc page can suggest a replace line for package users
if the godoc program finds that the hosting path and the module path specified
in the go.mod file are not consistent.

An example for the TinyRouter doc page:

====

package tinyrouter

import "github.com/go101/tinyrouter" // for GOPATH based projects

import "go101.org/tinyrouter" // for modules based projects

Please add the following line in your go.mod file to use this package
if your project is modules based:

replace go101.org/tinyrouter => github.com/go101/tinyrouter v1.0.1

@galxy25

This comment has been minimized.

galxy25 commented Nov 24, 2018

+1 for @go101 A suggestion: the godoc.org page for a package containing the go.mod file should also show an import/replace path specified in the go.mod file. updating a public GO sdk to be modules based and now the published Godoc page for the module has an incorrect module import 🤦🏾‍♂️

@bcmills bcmills added the modules label Nov 29, 2018

@mattouille

This comment has been minimized.

mattouille commented Dec 8, 2018

If godoc could support doing previews for an individual package (in the context of a directory rather than through package discovery) I think that might help a lot of use cases in the near term. Even if this were a temporary feature I think it'd go a long way.

If godoc can already do this I'd love to hear about it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment