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/pkgsite: examples in external test packages are not runnable #62059

Open
matthewdale opened this issue Aug 16, 2023 · 6 comments
Open

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

matthewdale opened this issue Aug 16, 2023 · 6 comments
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite

Comments

@matthewdale
Copy link

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

Screenshot 2023-08-05 at 4 37 42 PM

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.

@gopherbot gopherbot added this to the Unreleased milestone Aug 16, 2023
@findleyr findleyr changed the title x/pkgsite: examples in packages with a v2+ major verison suffix are not runnable x/pkgsite: examples in packages with a v2+ major version suffix are not runnable Aug 16, 2023
@findleyr
Copy link
Contributor

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?

@findleyr findleyr added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Aug 16, 2023
@seankhliao
Copy link
Member

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

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 findleyr modified the milestones: Unreleased, pkgsite/backlog Aug 24, 2023
@findleyr findleyr changed the title x/pkgsite: examples in packages with a v2+ major version suffix are not runnable x/pkgsite: examples in external test packages are not runnable Aug 24, 2023
@findleyr
Copy link
Contributor

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

@matthewdale
Copy link
Author

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

keep94 commented Oct 27, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Projects
None yet
Development

No branches or pull requests

5 participants