Repository: abhinav/doc2go (go)

Issue:
Hide Index heading for commands
Currently, doc2go puts an Index heading even when generating documentation for commands.

Compare:
- https://go.astrophena.name/tools/cmd/cmdtop (from my [vanity import domain](https://github.com/astrophena/vanity), docs generated by doc2go)
- https://pkg.go.dev/go.astrophena.name/tools/cmd/cmdtop (pkg.go.dev documentation)

I think it can be removed.

Pull request:
Don't render types and functions in main packages
For main packages, the only consumable part is the command.
There's no need to include the documentation of exported types defined
in main packages, because it's impossible to import and consume them.

To do this, a new command.html template is introduced.
This allows removing command-specific special cases from the package.html.

Resolves #210

Patch:
diff --git a/.changes/unreleased/Changed-20240221-073146.yaml b/.changes/unreleased/Changed-20240221-073146.yaml
new file mode 100644
index 0000000..b34bb38
--- /dev/null
+++ b/.changes/unreleased/Changed-20240221-073146.yaml
@@ -0,0 +1,6 @@
+kind: Changed
+body: >-
+  Don't render types and functions in main packages.
+  The only consumable part of these is the command itself.
+  Subpackages will still be rendered as before.
+time: 2024-02-21T07:31:46.540936-08:00
diff --git a/internal/html/render.go b/internal/html/render.go
index a4ba62c..c0d21ff 100644
--- a/internal/html/render.go
+++ b/internal/html/render.go
@@ -44,6 +44,13 @@ var (
 				"tmpl/package.html", "tmpl/layout.html", "tmpl/subpackages.html", "tmpl/pagefind.html"),
 	)
 
+	_commandTmpl = template.Must(
+		template.New("command.html").
+			Funcs((*render)(nil).FuncMap()).
+			ParseFS(_tmplFS,
+				"tmpl/command.html", "tmpl/layout.html", "tmpl/subpackages.html", "tmpl/pagefind.html"),
+	)
+
 	_packageIndexTmpl = template.Must(
 		template.New("directory.html").
 			Funcs((*render)(nil).FuncMap()).
@@ -250,7 +257,15 @@ func (r *Renderer) RenderPackage(w io.Writer, info *PackageInfo) error {
 		SubDirDepth:           info.SubDirDepth,
 		Pagefind:              r.Pagefind,
 	}
-	return errtrace.Wrap(template.Must(_packageTmpl.Clone()).
+
+	var tmpl *template.Template
+	if info.BinName != "" {
+		tmpl = _commandTmpl
+	} else {
+		tmpl = _packageTmpl
+	}
+
+	return errtrace.Wrap(template.Must(tmpl.Clone()).
 		Funcs(render.FuncMap()).
 		ExecuteTemplate(w, r.templateName(), info))
 }
diff --git a/internal/html/tmpl/command.html b/internal/html/tmpl/command.html
new file mode 100644
index 0000000..1093e54
--- /dev/null
+++ b/internal/html/tmpl/command.html
@@ -0,0 +1,18 @@
+{{ define "Head" -}}
+<title>{{ .BinName }}</title>
+{{ end -}}
+
+{{ define "PkgVersion" }}{{ with .PkgVersion }}{{ . }} | {{ end }}{{ end }}
+
+{{ define "Body" -}}
+<h2 id="pkg-overview" {{- if pagefind }} data-pagefind-meta="Import path:{{ .ImportPath }}"{{end }}>
+  {{- /**/ -}}
+  {{- .BinName -}}
+</h2>
+
+{{ .Doc | doc 3 -}}
+
+{{ with (filterSubpackages .Subpackages) -}}
+  {{ template "subpackages.html" . -}}
+{{ end -}}
+{{ end }}
diff --git a/internal/html/tmpl/package.html b/internal/html/tmpl/package.html
index b081d51..ed63f71 100644
--- a/internal/html/tmpl/package.html
+++ b/internal/html/tmpl/package.html
@@ -1,7 +1,5 @@
 {{ define "Head" -}}
-<title>
-  {{- with .BinName }}{{ . }}{{ else }}{{ .Name }}{{ end -}}
-</title>
+<title>{{ .Name }}</title>
 {{ end -}}
 
 {{ define "PkgVersion" }}{{ with .PkgVersion }}{{ . }} | {{ end }}{{ end }}
@@ -9,7 +7,8 @@
 
 {{ define "Body" -}}
 <h2 id="pkg-overview" {{- if pagefind }} data-pagefind-meta="Import path:{{ .ImportPath }}"{{end }}>
-  {{- with .BinName }}{{ . }}{{ else }}package {{ .Name }}{{ end -}}
+  {{- /**/ -}}
+  package {{ .Name -}}
 </h2>
 {{ .Import | code }}
 {{ .Doc | doc 3 -}}
diff --git a/main.go b/main.go
index a395809..074599f 100644
--- a/main.go
+++ b/main.go
@@ -1,4 +1,6 @@
 // doc2go generates static HTML documentation from one or more Go packages.
+//
+// See https://abhinav.github.io/doc2go/ for information on how to use it.
 package main
 
 import (


Test patch:
diff --git a/internal/html/render_test.go b/internal/html/render_test.go
index 6f51415..221d5b8 100644
--- a/internal/html/render_test.go
+++ b/internal/html/render_test.go
@@ -80,6 +80,7 @@ func TestRenderer_RenderPackage_title(t *testing.T) {
 		give          godoc.Package
 		wantHeadTitle string // contents of <title>
 		wantBodyTitle string // page header
+		wantIndex     bool   // whether #pkg-index is present
 	}{
 		{
 			desc: "library",
@@ -89,6 +90,7 @@ func TestRenderer_RenderPackage_title(t *testing.T) {
 			},
 			wantHeadTitle: "foo",
 			wantBodyTitle: "package foo",
+			wantIndex:     true,
 		},
 		{
 			desc: "binary",
@@ -128,6 +130,13 @@ func TestRenderer_RenderPackage_title(t *testing.T) {
 			bodyTitle := querySelector(doc, "#pkg-overview")
 			require.NotNil(t, bodyTitle)
 			assert.Equal(t, tt.wantBodyTitle, allText(bodyTitle))
+
+			index := querySelector(doc, "#pkg-index")
+			if tt.wantIndex {
+				require.NotNil(t, index)
+			} else {
+				assert.Nil(t, index)
+			}
 		})
 	}
 }