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.

Sign up for GitHub

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

Jump to bottom

feat: Allow packages to define custom documentation URL and badge #147

Merged
merged 3 commits into from
May 21, 2024
Merged

feat: Allow packages to define custom documentation URL and badge #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
79134a4
feat: Allow packages to define custom doc URL and badge
m5ka Apr 26, 2024
625ec66
Merge branch 'master' into main
JacobOaks Apr 29, 2024
4d245fc
Merge branch 'master' into main
r-hang May 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,18 @@ packages:
#
# Defaults to the value of the top-level url field.
url: example.com

# Optional URL to the package's documentation.
#
# Defaults to the documentation site at pkg.go.dev with the package's
# module path appended.
doc_url: example.com/go-pkg/docs/zap

# Optional URL to the badge image which appears in the index page.
#
# Defaults to the badge image at pkg.go.dev, using the package's module
# path followed by .svg as the filename.
doc_badge: example.com/go-pkg/badge/zap
```

Run sally like so:
Expand Down
13 changes: 13 additions & 0 deletions config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,19 @@ type PackageConfig struct {

// Desc is a plain text description of this module.
Desc string `yaml:"description"`

// DocURL is the link to this module's documentation.
//
// Defaults to the base doc URL specified in the top-level config
// with the package path appended.
DocURL string `yaml:"doc_url"`

// DocBadge is the URL of the badge which links to this module's
// documentation.
//
// Defaults to the pkg.go.dev badge URL with this module's path as a
// parameter.
DocBadge string `yaml:"doc_badge"`
}

// Parse takes a path to a yaml file and produces a parsed Config
Expand Down
15 changes: 14 additions & 1 deletion handler.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,13 +57,23 @@ func CreateHandler(config *Config, templates *template.Template) (http.Handler,
baseURL = pkg.URL
}
modulePath := path.Join(baseURL, name)
docURL := "https://" + path.Join(config.Godoc.Host, modulePath)

docURL := pkg.DocURL
if docURL == "" {
docURL = "https://" + path.Join(config.Godoc.Host, modulePath)
}

docBadge := pkg.DocBadge
if docBadge == "" {
docBadge = "//pkg.go.dev/badge/" + modulePath + ".svg"
}

pkg := &sallyPackage{
Name: name,
Desc: pkg.Desc,
ModulePath: modulePath,
DocURL: docURL,
DocBadge: docBadge,
VCS: pkg.VCS,
RepoURL: pkg.Repo,
}
Expand Down Expand Up @@ -106,6 +116,9 @@ type sallyPackage struct {
// URL at which documentation for the package can be found.
DocURL string

// URL at which documentation badge image can be found.
DocBadge string

// Version control system used by the package.
VCS string

Expand Down
41 changes: 41 additions & 0 deletions handler_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ packages:
repo: github.com/yarpc/metrics
net/something:
repo: github.com/yarpc/something
scago:
repo: github.com/m5ka/scago
doc_url: https://example.org/docs/go-pkg/scago
doc_badge: https://img.shields.io/badge/custom_docs-scago-blue?logo=go

`

Expand All @@ -41,6 +45,7 @@ func TestIndex(t *testing.T) {
assert.Contains(t, body, "A fast, structured logging library.")
assert.Contains(t, body, "github.com/yarpc/metrics")
assert.Contains(t, body, "github.com/yarpc/something")
assert.Contains(t, body, "github.com/m5ka/scago")
}

func TestSubindex(t *testing.T) {
Expand All @@ -49,6 +54,7 @@ func TestSubindex(t *testing.T) {

body := rr.Body.String()
assert.NotContains(t, body, "github.com/thriftrw/thriftrw-go")
assert.NotContains(t, body, "github.com/m5ka/scago")
assert.NotContains(t, body, "github.com/yarpc/yarpc-go")
assert.Contains(t, body, "github.com/yarpc/metrics")
assert.Contains(t, body, "github.com/yarpc/something")
Expand Down Expand Up @@ -189,6 +195,41 @@ func TestPackageLevelURL(t *testing.T) {
`)
}

func TestCustomDocURL(t *testing.T) {
rr := CallAndRecord(t, config, getTestTemplates(t, nil), "/scago")
AssertResponse(t, rr, 200, `
<!DOCTYPE html>
<html>
<head>
<meta name="go-import" content="go.uber.org/scago git https://github.com/m5ka/scago">
<meta http-equiv="refresh" content="0; url=https://example.org/docs/go-pkg/scago">
<style>
@media (prefers-color-scheme: dark) {
body { background-color: #333; color: #ddd; }
a { color: #ddd; }
a:visited { color: #bbb; }
}
</style>
</head>
<body>
Nothing to see here. Please <a href="https://example.org/docs/go-pkg/scago">move along</a>.
</body>
</html>
`)
}

func TestCustomDocBadge(t *testing.T) {
rr := CallAndRecord(t, config, getTestTemplates(t, nil), "/")
assert.Equal(t, 200, rr.Code)

body := rr.Body.String()
assert.Contains(t, body, "<img src=\"//pkg.go.dev/badge/go.uber.org/yarpc.svg\" alt=\"Go Reference\" />")
assert.Contains(t, body, "<img src=\"//pkg.go.dev/badge/go.uberalt.org/zap.svg\" alt=\"Go Reference\" />")
assert.Contains(t, body,
"<img src=\"https://img.shields.io/badge/custom_docs-scago-blue?logo=go\" alt=\"Go Reference\" />")
assert.NotContains(t, body, "<img src=\"//pkg.go.dev/badge/go.uber.org/scago.svg\" alt=\"Go Reference\" />")
}

func TestPostRejected(t *testing.T) {
t.Parallel()

Expand Down
2 changes: 1 addition & 1 deletion templates/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@
</div>
<div class="two columns">
<a href="{{ .DocURL }}">
<img src="//pkg.go.dev/badge/{{ .ModulePath }}.svg" alt="Go Reference" />
<img src="{{ .DocBadge }}" alt="Go Reference" />
</a>
</div>
</div>
Expand Down