Skip to content

feat(info): show driver docs URL in dbc info - #511

Open
djfrancesco wants to merge 2 commits into
columnar-tech:mainfrom
djfrancesco:feat/info-docs-url
Open

djfrancesco wants to merge 2 commits into
columnar-tech:mainfrom
djfrancesco:feat/info-docs-url

Conversation

@djfrancesco

Copy link
Copy Markdown

Closes #499

Summary

dbc docs already uses the docs_url from the registry index, but dbc info never showed it. This PR adds it to both the plaintext and the JSON output.

In plaintext, there's a new Docs: line after Description:. It only shows up when the driver has a docs URL:

$ dbc info snowflake
Driver: snowflake
Version: 1.14.0
Title: ASF Snowflake Driver
License: Apache-2.0
Description: An ADBC driver for Snowflake developed under the Apache Software Foundation
Docs: https://adbc-drivers.org/drivers/snowflake/
Available Packages:
   - linux_amd64
   ...

With --json, the driver.info payload gets a docs_url field:

{"schema_version":1,"kind":"driver.info","payload":{"driver":"snowflake", ..., "description":"...","docs_url":"https://adbc-drivers.org/drivers/snowflake/","packages":[...]}}

A few choices I made

I went with Docs: as the label since it's short and matches dbc docs. Drivers without a docs URL get no line at all, so their output doesn't change.

In the JSON, docs_url is always there (empty string when unset). I left out omitempty on purpose, so it behaves like title, license and description right next to it. The field is new, so schema_version stays at 1.

Easy to change any of these if you'd prefer something else.

The tests reuse the existing test-driver-docs-url fixture, and also check that a driver without a docs URL gets no Docs: line and an empty docs_url.

Not in this PR

dbc search -v --json doesn't include docs_url either. I can do that in a follow-up if you want it.

Test plan

  • go test ./... passes with Go 1.26.8 (env and user levels)
  • New tests fail without the change and pass with it
  • go vet ./... clean; changed files are gofmt-clean
  • Manual: dbc info snowflake and dbc info snowflake --json against the default registry show the docs URL

Display the registry's docs_url for a driver in `dbc info` output:
a "Docs:" line in plaintext (only when set) and a docs_url field in
the --json payload (always present, empty when unset).

Closes columnar-tech#499

@amoeba amoeba left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great. Just two small changes.

Thanks for taking the time to contribute here!

Comment thread cmd/dbc/info.go Outdated
b.WriteString(bold.Render("License: ") + drv.License + "\n")
b.WriteString(bold.Render("Description: ") + drv.Desc + "\n")
if drv.DocsURL != "" {
b.WriteString(bold.Render("Docs: ") + drv.DocsURL + "\n")

@amoeba amoeba Oct 6, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about using Hyperlink here? Many modern/popular terminals have auto-detection and don't need OSC8 control codes to make hyperlinks clickable but for (1) users who turn auto-detection off or (2) use terminals that don't support OSC8 control codes, this is slightly better. It looks like I missed doing this to the URL in dbc docs so we could do a follow-up PR to fix that.

I also think we should use the full word "Documentation" here. I take your point about using "Docs" to which matches the subcommand but the other fields here don't abbreviate.

Suggested change
b.WriteString(bold.Render("Docs: ") + drv.DocsURL + "\n")
b.WriteString(bold.Render("Documentation: ") + lipgloss.NewStyle().Hyperlink(drv.DocsURL).Underline(true).Render(drv.DocsURL) + "\n")

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you so much for your time @amoeba !
I agree with the full word "Documentation" instead of "Docs". No need for shortening...
About OSC 8, I didn't know about it but I like everything that can be done in the terminal.
Both changes are in b6a1ca7: Documentation: as the label, and the URL rendered with Hyperlink + underline. I had to add the charm.land/lipgloss/v2 import to info.go for it to build. Piped output is still plain text, since lipgloss.Println strips the escape codes.
I'd be happy to do the dbc docs follow-up too.

Comment thread cmd/dbc/info_test.go Outdated
"Available Packages:\n"+
" - linux_amd64\n - macos_amd64\n"+
" - macos_arm64\n - windows_amd64", out)
suite.NotContains(out, "Docs:")

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
suite.NotContains(out, "Docs:")
suite.NotContains(out, "Documentation:")

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Address review feedback: spell out the "Documentation:" label to
match the other unabbreviated fields, and render the URL as an
underlined OSC 8 hyperlink so it is clickable in terminals without
URL auto-detection. Escape codes are still stripped when stdout is
not a terminal.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add dbc docs url to dbc info

2 participants