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: remove CLI support in Go 1.12 #25443

Closed
bradfitz opened this issue May 17, 2018 · 39 comments

Comments

Projects
None yet
@bradfitz
Copy link
Member

commented May 17, 2018

Now that we have the cmd/go "go doc" CLI for getting documentation, does it make sense for x/tools/cmd/godoc to also have CLI support?

I propose we delete x/tools/cmd/godoc's CLI support and keep it being a web-only tool. Users who want CLI support can use "go doc". Both are shipped with Go releases.

/cc @dsnet @andybons @stamblerre @shantuo @robpike

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

@gopherbot gopherbot added the Proposal label May 17, 2018

@bradfitz

This comment has been minimized.

Copy link
Member Author

commented May 17, 2018

As background, this is motivated by the Go team maintaining something like 5 variations of "godoc" tools at the moment, and there's too much duplication and maintenance effort.

@bradfitz

This comment has been minimized.

Copy link
Member Author

commented May 17, 2018

@ianthehat mentioned that many IDEs invoke the godoc binary from releases to get documentation. Which ones? Can we convert them to use "go doc"?

@bradfitz

This comment has been minimized.

Copy link
Member Author

commented May 17, 2018

Or for such IDEs, it was proposed that we could perhaps make the "godoc" binary detect when it's in "legacy CLI mode" and invoke the "go doc" command as a subcommand instead?

@agnivade

This comment has been minimized.

Copy link
Member

commented May 17, 2018

As one such example - #16183 needs a fix to both godoc and go doc.

@rsc

This comment has been minimized.

Copy link
Contributor

commented May 21, 2018

@ianthehat, the IDE issue just means we have to coordinate this over multiple releases if we do it. If we decide to do it, then we can work on making it smooth. Personally I'm +1 on simplifying so that "godoc" is always just the package web server and not also the main web site nor a command-line doc viewer.

It also might be better to just drop the name "godoc" entirely, to avoid confusion with "go doc" and also godoc.org. The web server could be godochttp/godocsrv/godocweb/etc.

@mpx

This comment has been minimized.

Copy link
Contributor

commented May 27, 2018

A single CLI documentation tool would be good.

godoc has some useful functionality that isn't present in go doc. Eg, output of full package documentation (#25595). I'd be in favour of adding this to go doc as an option.

Another example might be HTML output from godoc. This probably isn't a good fit for go doc. Maybe godoc could continue to have a cut-down mode that only outputs full package doc in HTML? I don't have any strong opinions here (I don't use it), but others might.

@bradfitz

This comment has been minimized.

Copy link
Member Author

commented Jul 16, 2018

Decision: we'll document in the Go 1.11 release notes that the Go 1.11 release will be the last to support CLI mode godoc (no space). In Go 1.12, users (and any IDEs?) will need to use go doc for the CLI mode.

@bradfitz bradfitz modified the milestones: Proposal, Go1.11 Jul 16, 2018

@bradfitz bradfitz changed the title proposal: x/tools/cmd/godoc: remove CLI support? x/tools/cmd/godoc: remove CLI support in Go 1.12 Jul 16, 2018

@bradfitz bradfitz self-assigned this Jul 16, 2018

@gopherbot

This comment has been minimized.

Copy link

commented Jul 31, 2018

Change https://golang.org/cl/126737 mentions this issue: doc/go1.11: add note to remove CLI support for godoc

@bradfitz bradfitz removed the Documentation label Jul 31, 2018

@bradfitz bradfitz modified the milestones: Go1.11, Go1.12 Jul 31, 2018

gopherbot pushed a commit that referenced this issue Jul 31, 2018

doc/go1.11: add note to remove CLI support for godoc
Updates #25443

Change-Id: I5e2f84f3cee6582807b2756ffac91e8583a2baec
Reviewed-on: https://go-review.googlesource.com/126737
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

jeet-parekh added a commit to jeet-parekh/go that referenced this issue Jul 31, 2018

doc/go1.11: add note to remove CLI support for godoc
Updates golang#25443

Change-Id: I5e2f84f3cee6582807b2756ffac91e8583a2baec
Reviewed-on: https://go-review.googlesource.com/126737
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
@gopherbot

This comment has been minimized.

Copy link

commented Oct 11, 2018

Change https://golang.org/cl/141397 mentions this issue: godoc, cmd/godoc: remove CLI support

@adg

This comment has been minimized.

Copy link
Contributor

commented Oct 11, 2018

What about @rsc's suggestion that we rename the godoc command to something else? I'm on the fence. I guess we could see if anyone gets confused first.

@bradfitz

This comment has been minimized.

Copy link
Member Author

commented Oct 11, 2018

@adg, I'm fine renaming it (assuming we find a good name) but I didn't want to do it in that CL.

I'd also rather push that decision out until the website rearchitecting plan is more solidified. I haven't heard the latest plan there in some time.

@adg

This comment has been minimized.

Copy link
Contributor

commented Oct 11, 2018

Sounds good.

@myitcv

This comment has been minimized.

Copy link
Member

commented Oct 11, 2018

Picking up on discussion with @adg in the CL.

I think this change being merged now will create a problem, per @ianthehat's comments, for VSCode (at least) which has a default of godoc. On the last golang-tools call, @ramya-rao-a mentioned that VSCode currently uses godoc by default, with the option of gogetdoc (which is what I think we see here).

I read https://golang.org/doc/go1.11#godoc as "godoc as a CLI will be around, but deprecated, for Go 1.11, and then not available in Go 1.12".

Given godoc is installed from x/tools, does this not break things pre Go 1.12?

@gopherbot

This comment has been minimized.

Copy link

commented Oct 11, 2018

Change https://golang.org/cl/141717 mentions this issue: cmd/godoc: synchronously init corpus for index mode

gopherbot pushed a commit to golang/tools that referenced this issue Oct 11, 2018

cmd/godoc: synchronously init corpus for index mode
The corpus needs to be init'd before generating the index.

Regression caused by CL 141397.

Updates golang/go#25443.

Change-Id: I04d19bf5d279031cc8ddf0f850d81eb06fc5efa8
Reviewed-on: https://go-review.googlesource.com/c/141717
Run-TryBot: Chris Broadfoot <cbro@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

segevfiner added a commit to segevfiner/vscode-go that referenced this issue Oct 26, 2018

WIP Add completion documentation
Using `go doc` instead of `godoc` due to
golang/go#25443

`go doc` doesn't support giving the code of an unsaved file via stdin
like `gocode`, so it won't display documentation for unsaved changes.

TODO: Make sure this works for all cases, the current file, main package,
etc...

Fixes microsoft#194

segevfiner added a commit to segevfiner/vscode-go that referenced this issue Oct 26, 2018

Add item documentation to completions
Using `go doc` instead of `godoc` due to
golang/go#25443

`go doc` doesn't seem to support giving the code of an unsaved file via
stdin like `gocode`, so it won't display documentation for unsaved
changes.

Fixes microsoft#194

segevfiner added a commit to segevfiner/vscode-go that referenced this issue Oct 26, 2018

Add item documentation to completions
Using `go doc` instead of `godoc` due to
golang/go#25443

`go doc` doesn't seem to support giving the code of an unsaved file via
stdin like `gocode`, so it won't display documentation for unsaved
changes.

Fixes microsoft#194
@gopherbot

This comment has been minimized.

Copy link

commented Oct 31, 2018

Change https://golang.org/cl/145222 mentions this issue: doc: replace command line usages of godoc with go doc

gopherbot pushed a commit that referenced this issue Oct 31, 2018

doc: replace command line usages of godoc with go doc
Effective Go and the FAQ still had some instances which showed the command line
usage of godoc. Changed them to use go doc.

Updates #25443

Change-Id: If550963322034e6848bc466f79e968e7220e4a88
Reviewed-on: https://go-review.googlesource.com/c/145222
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

ramya-rao-a added a commit to microsoft/vscode-go that referenced this issue Nov 1, 2018

Add item documentation to completions (#2054)
* Add item documentation to completions

Using `go doc` instead of `godoc` due to
golang/go#25443

`go doc` doesn't seem to support giving the code of an unsaved file via
stdin like `gocode`, so it won't display documentation for unsaved
changes.

Fixes #194

* Code review fixes for #2054

* Refactoring and comments

* Always resolve the item

* Prompt for updating gocode if the package property is missing
@gopherbot

This comment has been minimized.

Copy link

commented Feb 18, 2019

Change https://golang.org/cl/162982 mentions this issue: godoc: remove unused CLI-only identifiers

@gopherbot

This comment has been minimized.

Copy link

commented Feb 18, 2019

Change https://golang.org/cl/162984 mentions this issue: cmd/godoc: re-add documentation for flat presentation mode

gopherbot pushed a commit to golang/tools that referenced this issue Feb 19, 2019

cmd/godoc: re-add documentation for flat presentation mode
The documentation of the "flat" presentation mode was removed
inadvertently as part of post-CLI-removal documentation cleanup
in CL 143077. The FlatDir flag still exists and is supported.
This change re-adds it to cmd/godoc documentation.

Also fix a typo in the "src" presentation mode description.

Updates golang/go#25443

Change-Id: If4705d70bc5eafee92cdfd52409aca4606a0efd7
Reviewed-on: https://go-review.googlesource.com/c/162984
Reviewed-by: Agniva De Sarker <agniva.quicksilver@gmail.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

gopherbot pushed a commit to golang/tools that referenced this issue Feb 19, 2019

godoc: remove unused CLI-only identifiers
This is a followup to CL 141397, which removed CLI support from the
godoc command for golang/go#25443. This change removes a few more
CLI-related fields from Presentation type, which are now unused.

It also removes the unused and no longer documented (since CL 143077)
NoHTML PageInfoMode.

Updates golang/go#25443

Change-Id: Ia4147515052889570e2f050e3c2394689d3c5d6c
Reviewed-on: https://go-review.googlesource.com/c/162982
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Agniva De Sarker <agniva.quicksilver@gmail.com>
@leucos

This comment has been minimized.

Copy link

commented Mar 3, 2019

Is there any way to generate HTML documentation like we could do with godoc ./package --html before 1.12 ? It seem that go doc has no provision for HTML output.

Currently resorting to this workaround

@dmitshur

This comment has been minimized.

Copy link
Member

commented Mar 3, 2019

@leucos You should be able to continue to use the -url flag of the godoc binary for that purpose.

$ godoc -help 2>&1 | grep -C 1 'url'
    	show timestamps with directory listings
  -url string
    	print HTML for named URL

$ godoc -url /pkg/go/format
<HTML documentation for package go/format>
@leucos

This comment has been minimized.

Copy link

commented Mar 3, 2019

Great, thanks @dmitshur , works like a charm. Sorry for the noise on a closed topic.

@trivigy

This comment has been minimized.

Copy link

commented Mar 19, 2019

@dmitshur Any suggestions as to how to do that when working with a local go module based development? I got godoc -html=:6060 to work but since my packages are on modules and not part of the GOPATH godoc is not listing them in the generated html.

@dmitshur

This comment has been minimized.

Copy link
Member

commented Mar 19, 2019

@trivigy The godoc command does not have support for module mode yet, but work on resolving that is underway. The umbrella issue #26827 is tracking that task, and you can subscribe to it for further updates.

@gopherbot

This comment has been minimized.

Copy link

commented Apr 23, 2019

Change https://golang.org/cl/172975 mentions this issue: godoc: declare small victory over the punched card tyranny

@gopherbot

This comment has been minimized.

Copy link

commented May 17, 2019

Change https://golang.org/cl/177737 mentions this issue: godoc: re-add test for ignoring //line comments in source code

gopherbot pushed a commit to golang/tools that referenced this issue May 17, 2019

godoc: declare small victory over the punched card tyranny
At least inside this one package.

It's because golang.org/x/tools/cmd/godoc no longer has CLI support
as of golang/go#25443, it is now only a web server. Luckily, browsers
that display HTML pages are not constrained to the fixed width of
punched cards. On the contrary, they seem to embrace a wide variety of
arbitrary page widths, ranging from narrow to wide. This is in part due
to the proliferation of internet access on device form factors such as
the mobile phone, tablet, laptop, and desktop.

So the punchCardWidth constant is now unused and can be removed. This
is a followup to CL 141397 that removed most of the CLI support code,
including the function comment_textFunc, which was its only user. Same
goes for containsOnlySpace.

Updates golang/go#25443

Change-Id: I61fabe6ea801c88758fb2c6aefa70b53d52e2cb5
Reviewed-on: https://go-review.googlesource.com/c/tools/+/172975
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

gopherbot pushed a commit to golang/tools that referenced this issue May 28, 2019

godoc: re-add test for ignoring //line comments in source code
The original CL 84050044 added a test case, and it happened to be
in between various CLI test cases. CLI support was removed from
x/tools/cmd/godoc in CL 141397, as part of golang/go#25443.
Re-add a test case for this behavior to prevent regressions.

Updates golang/go#32092
Updates golang/go#25443
Updates golang/go#5247

Change-Id: I0cea74cfe40d120e398a9005676134c5bad6136c
Reviewed-on: https://go-review.googlesource.com/c/tools/+/177737
Reviewed-by: Robert Griesemer <gri@golang.org>
@gingerhot

This comment has been minimized.

Copy link

commented Jun 3, 2019

Before v1.12, I can use godoc -html <a relative path not in GOPATH> to generate godoc output to a specified path, but now I don't know how to achieve this. I think there should be an equivalent go doc -html as well.

Otherwise where is the Go claimed backward compatibility?

@bradfitz

This comment has been minimized.

Copy link
Member Author

commented Jun 3, 2019

Otherwise where is the Go claimed backward compatibility?

The Go compatibility promise excludes tools: https://golang.org/doc/go1compat#tools

@gingerhot

This comment has been minimized.

Copy link

commented Jun 3, 2019

@bradfitz thanks for your reply and clarifying of it. I misunderstood it.

But I still hope there's a such go doc -html subcommand option.

@dmitshur

This comment has been minimized.

Copy link
Member

commented Jun 3, 2019

Before v1.12, I can use godoc -html <a relative path not in GOPATH> to generate godoc output to a specified path, but now I don't know how to achieve this.

@gingerhot Have you considered the godoc -url flag? It can be used to achieve very similar results. See a comment above.

@gingerhot

This comment has been minimized.

Copy link

commented Jun 3, 2019

@dmitshur Thank you for response. I've read your solution above, it's awesome for those packages within the GOPATH, I need do some tricks to make it work for those packages outside the GOPATH in my situation. Such as put the code under a src folder and set an adhoc GOPATH env before the command, but it does work. Thanks again.

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.