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.

Sign up for GitHub

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

Jump to bottom

x/tools/cmd/godoc: remove CLI support in Go 1.12 #25443

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

x/tools/cmd/godoc: remove CLI support in Go 1.12 #25443

bradfitz opened this issue May 17, 2018 · 40 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. Proposal Proposal-Accepted
Milestone
Go1.12

Comments

@bradfitz
Copy link
Contributor

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
@bradfitz
Copy link
Contributor Author

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
Copy link
Contributor Author

@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
Copy link
Contributor Author

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

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

@rsc
Copy link
Contributor

rsc 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 mpx mentioned this issue May 27, 2018
Closed
@mpx
Copy link
Contributor

mpx 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
Copy link
Contributor Author

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
@bradfitz bradfitz added Documentation Issues describing a change to documentation. NeedsFix The path to resolution is known, but the work has not been done. labels Jul 16, 2018
@gopherbot
Copy link
Contributor

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

@DeedleFake DeedleFake mentioned this issue Jul 31, 2018
Open
@bradfitz bradfitz removed the Documentation Issues describing a change to 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
@agnivade @bradfitz
doc/go1.11: add note to remove CLI support for godoc

Unverified

This commit is not signed, but one or more authors requires that any commit attributed to them is signed.
Learn about vigilant mode
137f2fb 
Updates #25443

Change-Id: I5e2f84f3cee6582807b2756ffac91e8583a2baec
Reviewed-on: https://go-review.googlesource.com/126737
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
jeet-parekh pushed a commit to jeet-parekh/go that referenced this issue Jul 31, 2018
@agnivade @jeet-parekh
doc/go1.11: add note to remove CLI support for godoc

Unverified

This commit is not signed, but one or more authors requires that any commit attributed to them is signed.
Learn about vigilant mode
48ab49a 
Updates golang#25443

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

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

@adg
Copy link
Contributor

adg 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
Copy link
Contributor Author

@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
Copy link
Contributor

adg commented Oct 11, 2018

Sounds good.

@myitcv
Copy link
Member

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

@segevfiner segevfiner mentioned this issue Oct 26, 2018
Merged
@gopherbot
Copy link
Contributor

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
@agnivade @robpike
doc: replace command line usages of godoc with go doc

Unverified

This commit is not signed, but one or more authors requires that any commit attributed to them is signed.
Learn about vigilant mode
3553eca 
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>
@buzztaiki buzztaiki mentioned this issue Nov 1, 2018
Closed
ramya-rao-a pushed a commit to microsoft/vscode-go that referenced this issue Nov 1, 2018
@segevfiner @ramya-rao-a
Add item documentation to completions (#2054)
3a693e5 
* 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
@shadowbq shadowbq mentioned this issue Nov 9, 2018
Open
@gopherbot
Copy link
Contributor

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

@gopherbot
Copy link
Contributor

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
@dmitshur @agnivade
cmd/godoc: re-add documentation for flat presentation mode

Unverified

This commit is not signed, but one or more authors requires that any commit attributed to them is signed.
Learn about vigilant mode
0a7d439 
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
@dmitshur
godoc: remove unused CLI-only identifiers
d38dac7 
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
Copy link

leucos 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
Copy link
Contributor

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

leucos commented Mar 3, 2019

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

@trivigy
Copy link

trivigy commented Mar 19, 2019 •
edited
Loading

@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
Copy link
Contributor

@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
Copy link
Contributor

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

@gopherbot
Copy link
Contributor

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
@dmitshur
godoc: declare small victory over the punched card tyranny
1da8801 
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
@dmitshur
godoc: re-add test for ignoring //line comments in source code
09281b5 
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
Copy link

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
Copy link
Contributor Author

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

gingerhot commented Jun 3, 2019 •
edited
Loading

@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
Copy link
Contributor

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

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

@gopherbot
Copy link
Contributor

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

gopherbot pushed a commit to golang/website that referenced this issue Sep 30, 2019
@dmitshur
cmd/golangorg: re-add documentation for flat presentation mode
42bb757 
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/golangorg documentation.

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

(This is a re-apply of CL 162984 into x/website.)

Updates golang/go#25443
Updates golang/go#29206

Change-Id: I84145bf38f008678a8d8f3d3346f646aa7811886
Reviewed-on: https://go-review.googlesource.com/c/website/+/197721
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@golang golang locked and limited conversation to collaborators Sep 29, 2020
henderjon pushed a commit to oggodoc/godoc that referenced this issue Jun 13, 2024
@bradfitz
godoc, cmd/godoc: remove CLI support
eae6902 
godoc is now just a webserver (the one that runs golang.org)

A future change might rename this to something else, but not now.

Fixes golang/go#25443

Change-Id: Ib95d0589e13f4c7a717ff28d694f1472e427eef4
Reviewed-on: https://go-review.googlesource.com/c/141397
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Andrew Gerrand <adg@golang.org>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. Proposal Proposal-Accepted
Projects
None yet
Milestone
Go1.12
Development

No branches or pull requests