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 · 17 comments

Comments

Projects
None yet
@agnivade
Copy link
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.

Copy link
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.

Copy link
Member Author

agnivade commented Aug 7, 2018

Indeed. Thank you.

@thepudds

This comment has been minimized.

Copy link

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.

Copy link
Member Author

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

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.

Copy link

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.

Copy link

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.

Copy link

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.

@thepudds

This comment has been minimized.

Copy link

thepudds 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

thepudds 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

mattouille 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

alexaandru 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

izgeri 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

dmitshur 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

alexaandru 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

odiferousmint 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

shuLhan 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.

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.