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

Open
agnivade opened this issue Aug 6, 2018 · 25 comments

Comments

Projects
None yet
@agnivade
Copy link
Member

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.

Copy link
Contributor

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.

Copy link
Member Author

commented Aug 7, 2018

Indeed. Thank you.

@thepudds

This comment has been minimized.

Copy link

commented Aug 8, 2018

@gopherbot please add modules label

@gopherbot gopherbot added the modules label Aug 8, 2018

@agnivade

This comment has been minimized.

Copy link
Member Author

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 x/tools/cmd/godoc: improvements to adapt to module aware repo structure x/tools/cmd/godoc, gddo: module support Oct 11, 2018

@acln0

This comment has been minimized.

Copy link
Contributor

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.

Copy link

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.

Copy link

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.

Copy link

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.

@thepudds

This comment has been minimized.

Copy link

commented Jan 4, 2019

Workaround from thread (similar to
#26827 (comment)):

The solution I came up with is to have a bash script like this in my Makefile:

mkdir -p /tmp/tmpgoroot/doc
rm -rf /tmp/tmpgopath/src/github.com/username/packagename
mkdir -p /tmp/tmpgopath/src/github.com/username/packagename
tar -c --exclude='.git' --exclude='tmp' . | tar -x -C /tmp/tmpgopath/src/github.com/username/packagename
echo -e "open http://localhost:6060/pkg/github.com/username/packagename\n"
GOROOT=/tmp/tmpgoroot/ GOPATH=/tmp/tmpgopath/ godoc -http=localhost:6060

Karel

@thepudds thepudds closed this Jan 4, 2019

@thepudds

This comment has been minimized.

Copy link

commented Jan 4, 2019

Reopening. (Sorry, fat fingered on my phone).

@thepudds thepudds reopened this Jan 4, 2019

@mattouille

This comment has been minimized.

Copy link

commented Jan 5, 2019

Yeah, this is more or less what I've been doing. Instead of dumping it in /tmp I actually put it where it should go in the GOPATH, do my changes, then move it back to my normal directory. I wonder if this can be done with symlinks? I don't know of any potential side effects either. I'll report back.

@alexaandru

This comment has been minimized.

Copy link

commented Feb 21, 2019

Yeah, this is more or less what I've been doing. Instead of dumping it in /tmp I actually put it where it should go in the GOPATH, do my changes, then move it back to my normal directory. I wonder if this can be done with symlinks? I don't know of any potential side effects either. I'll report back.

No go with symlinks, but sudo mount -o bind does the trick :) Now I can keep my project in only one place and let godoc see it where it wants to see it... :)

@izgeri

This comment has been minimized.

Copy link

commented Feb 22, 2019

We are working on a workaround with Docker - mounting our code in as a volume and running godoc from the container. But really, it would be nice if we could run it locally as intended.

@dmitshur

This comment has been minimized.

Copy link
Member

commented Feb 22, 2019

But really, it would be nice if we could run it locally as intended.

There is planning work being done with the goal of making that the case. I will be posting more updates in the coming weeks. Thanks for your patience on this.

@alexaandru

This comment has been minimized.

Copy link

commented Feb 23, 2019

There is now https://github.com/neilotoole/gohdoc :-) which does exactly that: show the docs for your project and only your project.

@odiferousmint

This comment has been minimized.

Copy link

commented Feb 23, 2019

There is now https://github.com/neilotoole/gohdoc :-) which does exactly that: show the docs for your project and only your project.

This doesn't seem to work for a project outside of GOPATH. It tells me Error: failed to find in server pkg list: myproj.

@shuLhan

This comment has been minimized.

Copy link
Contributor

commented Feb 27, 2019

@acln0 @thepudds

This comment is a note for anyone who want to run godoc web on local system.

GOPATH actually allow multiple directory separated by ":", much like PATH. My source code is structured like GOPATH, for example, inside $HOME directory I have,

src
├── github.com
│   ├── github
│   ├── Go-ID-community
│   ├── golangci
│   └── shuLhan
├── gitlab.com
│   └── shuLhan
└── golang.org
    └── x

and then in another directory $HOME/work I have Go repositories for work related.

Combining this two directories, I can run a local godoc using user systemd service,

master ms 0 % cat .config/systemd/user/godoc.service
[Unit]
Description=godoc

[Service]
Type=simple
Environment=GOROOT=/home/ms/git/go
Environment=GOPATH=/home/ms:/home/ms/work
ExecStart=/home/ms/bin/godoc -v -http=:6060 -goroot=${GOROOT} -play -index -index_files=/home/ms/.cache/godoc.index

[Install]
WantedBy=default.target

Then I can run the service with systemctl --user start godoc and view the local godoc on web browser.

@trivigy

This comment has been minimized.

Copy link

commented May 30, 2019

@dmitshur

There is planning work being done with the goal of making that the case. I will be posting more updates in the coming weeks. Thanks for your patience on this.

Just checking in to see if there has been any development on this front?

@trivigy

This comment has been minimized.

Copy link

commented Jun 15, 2019

After using @thepudds workaround from above I decided to add another that eliminates the need for creating special tmp folders. This one requires docker installed. It's a simple linux bash alias that runs a function which starts docker, attaches the current directory as a volume, and configures the necessary setup inside the container. Just one liner. Tested it only on debian.

If you need a different version of golang just make sure to change the docker image tag.

# start godoc inside docker (https://github.com/golang/go/issues/26827)
alias godoc=$'function _godoc() { [ ! -f "$(pwd)/go.mod" ] && echo "error: go.mod not found" || module=$(awk \'NR==1{print $2}\' go.mod) && docker run --rm -e "GOPATH=/tmp/go" -p 6060:6060 -v $(pwd):/tmp/go/src/$module golang:1.12.6 /bin/bash -c "awk \'END{print \\\"http://\\\"\\$1\\\":6060/pkg/$module\\\"}\' /etc/hosts && godoc -http=:6060"; unset -f _godoc; }; _godoc'

The alias will print the url where you need to navigate. Make sure to run it from project directory where go.mod can be found.

@dfang

This comment was marked as off-topic.

Copy link

commented Jun 18, 2019

it would be great to have mod support when develop locally so that godoc can view unpublish docs

@mvdan

This comment has been minimized.

Copy link
Member

commented Jun 18, 2019

Please remember to not leave +1 comments; see https://github.com/golang/go/wiki/NoPlusOne.

@dfang

This comment was marked as off-topic.

Copy link

commented Jun 19, 2019

@mvdan it's not off-topic. i mean when i develop a package outside of $GOPATH. you want show it's doc before publishing it to github, you have to ln to $GOPATH for now.

@schrej

This comment has been minimized.

Copy link

commented Jun 19, 2019

@mvdan it's not off-topic. i mean when i develop a package outside of $GOPATH. you want show it's doc before publishing it to github, you have to ln to $GOPATH for now.

The issue is about adding support for go modules to godoc.
You saying that it would be good to have go module support in godoc without adding any additional information is essentially just a longer version of writing +1.

@stapelberg

This comment has been minimized.

Copy link
Contributor

commented Jun 21, 2019

cc @bcmills — this issue is open for almost a year.

Is it particularly hard to make godoc work with modules (at least making the module in $PWD available seems pretty straight-forward?), or did this fall through the cracks?

Thanks,

@mvdan

This comment has been minimized.

Copy link
Member

commented Jun 21, 2019

Just to give some context - this issue has been discussed as part of golang-tools multiple times in the past year, so it's definitely not forgotten.

My understanding is that this is indeed a hard problem. Perhaps the team can share details (or failed experiments) to keep us updated, or to specify how the community can help.

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