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

feat: Allow packages to define custom doc URL and badge Co-authored-by: Jacob Oaks <jacoboaks.8@gmail.com> Co-authored-by: r-hang <rhang@uber.com>
uber-go · May 21, 2024 · d9a9a90 · d9a9a90
1 parent e6df748
commit d9a9a90
Show file tree

Hide file tree

Showing 5 changed files with 81 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -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:

diff --git a/config.go b/config.go
@@ -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

diff --git a/handler.go b/handler.go
@@ -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,
 		}
@@ -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
 

diff --git a/handler_test.go b/handler_test.go
@@ -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
 
 `
 
@@ -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) {
@@ -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")
@@ -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()
 

diff --git a/templates/index.html b/templates/index.html
@@ -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>