x/pkgsite: examples in external test packages are not runnable

[matthewdale]

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/urfave/cli/v3@v3.0.0-alpha4#example-Command.Run-NoAction

This reports a bug that renders some testable examples without a main block, making them not runnable. It seems to happen anytime the import path ends with a vN major version suffix that doesn't match the package name.

See the corresponding testable example code here and the import that ends in /v3 here. Using an import alias that matches the package name resolves the issue. For example:

import cli "github.com/urfave/cli/v3"

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/113.0

Screenshot

What did you do?

Go to https://pkg.go.dev/github.com/urfave/cli/v3@v3.0.0-alpha4#example-Command.Run-NoAction and try to run the "NoAction" example (or any example for the github.com/urfave/cli/v3 package).

What did you expect to see?

A runnable code example with a main block and a "Run" button.

What did you see instead?

A code example with no main block and no "Run" button.

[findleyr]

It doesn't look like any of the examples here are runnable either:
https://pkg.go.dev/github.com/urfave/cli

Am I missing something? Are we sure the problem is related to the /v3 suffix?

[seankhliao]

is it a difference between package thing and package thing_test ?
Though I'm unsure which should work, since urfave/cli has them all in cli_test, nothing shows while mine in https://pkg.go.dev/go.seankhliao.com/testrepo0310/v2 only the _test one shows

[matthewdale]

I believe @seankhliao is correct. The "v1" testable examples are in the cli package rather than the cli_test package, which also prevents the examples from being runnable. Check out the "NoAction" example here and the corresponding test code here.

For "v3", the testable examples were moved into the cli_test package, but are also not runnable (seemingly because they have a major version suffix).

[findleyr]

Thanks, unfortunately this has to go into our backlog, as we don't have resources to work on this right now.

[matthewdale]

I think this may actually be a bug (or missing feature) in the go/doc example parser. I created a playground example that uses doc.Examples to parse a "playable" example from a test that imports a package with a major version suffix: https://go.dev/play/p/V8RY15XlJZy

Notice that doc.Examples is not able to create a "playable" example when the package ends in v3 (instead of cli) unless you specify an import alias. Since the major version suffix is a requirement for v2+ Go modules, it seems like the go/doc package should know how to handle them.

[keep94]

I noticed a similar issue on https://pkg.go.dev/github.com/keep94/sqroot/v2. The examples in this package don't have a run button even though the v2/example_test.go file is in the sqroot_test package and imports "github.com/keep94/sqroot/v2" However https://pkg.go.dev/github.com/keep94/sqroot, the v1 version, has runnable examples.