go/doc, x/pkgsite: examples not rendered according to the testing documentation; includes unwanted code #43658
What is the URL of the page with the issue?
What is your user agent?
Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0
What did you do?
Navigate to the linked example.
What did you expect to see?
According to the testing documentation
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:
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:
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 <firstname.lastname@example.org> Run-TryBot: Jonathan Amsterdam <email@example.com> TryBot-Result: kokoro <firstname.lastname@example.org> Reviewed-by: Julie Qiu <email@example.com>
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 <firstname.lastname@example.org> Run-TryBot: Jonathan Amsterdam <email@example.com> TryBot-Result: kokoro <firstname.lastname@example.org> Reviewed-by: Julie Qiu <email@example.com>
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 <firstname.lastname@example.org> Reviewed-by: Robert Findley <email@example.com> Run-TryBot: Jonathan Amsterdam <firstname.lastname@example.org>