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

proposal: x/tools/cmd/godoc: add -exclude_gopath #25364

Closed
paulswanson opened this issue May 13, 2018 · 1 comment

Comments

Projects
None yet
3 participants
@paulswanson
Copy link

commented May 13, 2018

It would be helpful to add an "-exclude_gopath" flag to godoc command.

Reason

Godoc automatically includes the default Go path value without any apparent option to disable this behaviour. It could be helpful in certain cases to disable this behaviour, for example, when a user wishes just to exam only the official Go standard library documentation and not EVERYTHING they currently have in their source folder. This would be helpful when a user is trying to learn Go by reading the official documentation in an offline mode by using "godoc -http". The current behaviour makes readability quite poor if the user has a large number of packages installed and is primarily interested in only the official documentation.

Currently, the user's $GOPATH environment variable can't even be used to temporarily override this default behaviour, for example:

~$ GOPATH="" godoc -http

This example command line fails because build.Default.GOPATH adds Go's default GOPATH value regardless.

Implementation

Rather than suggest a change to the build context default, I'm proposing that a flag be added to the godoc cmd that enables a user to simply exclude the GOPATH source files from a godoc command session.

The following lines would be added to / changed in main.go:

excludeGopath = flag.Bool("exclude_gopath", false, "exclude packages in $GOPATH")

if !*excludeGoPath {
	// Bind $GOPATH trees into Go root.
	for _, p := range filepath.SplitList(build.Default.GOPATH) {
		fs.Bind("/src", gatefs.New(vfs.OS(p), fsGate), "/src", vfs.BindAfter)
	}
}

This proposal avoids any platform specific issues by simply entirely bypassing the processing of that path. If any future changes were to the underling default context to better support this behaviour it could easily be rolled back.

Note

If this proposed change is accepted then I'd naturally be happy to write it up.

@gopherbot gopherbot added this to the Proposal milestone May 13, 2018

@gopherbot gopherbot added the Proposal label May 13, 2018

@agnivade

This comment has been minimized.

Copy link
Member

commented May 13, 2018

@paulswanson - Thank you for raising the issue. This is a dup of #25158.

This example command line fails because build.Default.GOPATH adds Go's default GOPATH value regardless.

Yes, only if your GOPATH is the default one, which is "/home/user/go". Hence when you set the env var to "", it falls back to that. Just set the env var to some dummy value like - none, or dummy

Also, note that the next version of godoc will group packages in the standard library and the GOPATH into separate collapsible sections. So they will be much more manageable, since I see that readability was also one of your concerns.

I am going to close this has been raised in the past and a reasonable alternative already exists. And godoc already has better segregation of user source libraries and the standard library in the next release.

Please comment if you disagree.

@agnivade agnivade closed this May 13, 2018

@golang golang locked and limited conversation to collaborators May 13, 2019

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.