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
go/doc, x/pkgsite: examples not rendered according to the testing documentation; includes unwanted code #43658
Comments
This has nothing to do with whole-file examples. It is related to our attempt to make examples playable (executable on the Go playground) by synthesizing a program from them. The code is the There are three bugs here:
|
Change https://golang.org/cl/285812 mentions this issue: |
When constructing a playable example, sort the import declarations in the usual way, with standard library imports first. For golang/go#43658 Change-Id: I47008caf6c2dfa0d66351e7ffb887b0880065fcd Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/285812 Trust: Jonathan Amsterdam <jba@google.com> Run-TryBot: Jonathan Amsterdam <jba@google.com> TryBot-Result: kokoro <noreply+kokoro@google.com> Reviewed-by: Julie Qiu <julie@golang.org>
Change https://golang.org/cl/285972 mentions this issue: |
There is another bug: the other example in the file (https://pkg.go.dev/gonum.org/v1/gonum/graph/community#example-Profile-Multiplex) uses variables that are set up in an |
… examples When synthesizing the code for a playable example, we need to include all the declared variables, types and functions that the example uses. This CL makes sure we don't include more than we need. If a declaration declared multiple names, like `var a, b int` or ``` var ( a int b string ) ``` then we would include the entire declaration, even if the example only used one of the variables. Keep track the names actually used, and prune the unused ones from the declarations. For golang/go#43658 Change-Id: Ia9e88ecd6d4ea50bd07fad6dfba219bfcb512f0d Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/285972 Trust: Jonathan Amsterdam <jba@google.com> Run-TryBot: Jonathan Amsterdam <jba@google.com> TryBot-Result: kokoro <noreply+kokoro@google.com> Reviewed-by: Julie Qiu <julie@golang.org>
The immediate issue is fixed, so closing this. The init function bug is still outstanding. I filed #44076 for it. |
If this is the solution, the documentation in the testing package describing example behaviour should be changed. It doesn't agree with this change. Or at the very least the pkgsite should say that it's forging ahead in its own direction. |
/cc @dmitshur I think "presented" is a case of the |
Thanks |
Change https://go.dev/cl/384837 mentions this issue: |
Change https://go.dev/cl/401758 mentions this issue: |
When synthesizing a program from a playable example, preserve the grouping of imports. That is, maintain blank lines between imports while removing unused ones. People are used to having those groups because that is what goimports does. It's disconcerting to see the all imports placed together, as the existing code does, especially when the user has already grouped them. For an example, see #43658. This is an improvement to a fix in pkgsite's fork of go/doc (https://go.googlesource.com/pkgsite/+/7b10ef3861af4a863bf215f63b6de94c681d5af0/internal/godoc/internal/doc/example_pkgsite.go#405). Here I've managed to avoid using a token.FileSet. Change-Id: I65605e6dd53d742a3fe1210c3f982b54e3706198 Reviewed-on: https://go-review.googlesource.com/c/go/+/384837 TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Robert Findley <rfindley@google.com> Run-TryBot: Jonathan Amsterdam <jba@google.com>
What is the URL of the page with the issue?
https://pkg.go.dev/gonum.org/v1/gonum/graph/community#example-Profile-Simple
What is your user agent?
Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0
Screenshot
What did you do?
Navigate to the linked example.
What did you expect to see?
According to the testing documentation
I expect to see just the body of the example as rendered on godoc.org since there is more than one example in the file.
What did you see instead?
Extraneous details also presented (and the imports mangled and helpful comments removed).
The parts included are used by the second example and so entirely unrelated to the first. The choice of including two examples in the file was specifically to prevent these details leaking to the reader since they do not help advance the documentation.
The text was updated successfully, but these errors were encountered: