content,internal/godoc: add table of contents to command pages

This change supports the table of contents section
in the overview section of command pages. This helps
give us feature parity with command pages on golang.org.

Fixes golang/go#38073

Change-Id: I396fcebbc569d046fc6ca7bf8beed037c9321a1b
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/288553
Trust: Jamal Carvalho <[email protected]>
Run-TryBot: Jamal Carvalho <[email protected]>
TryBot-Result: kokoro <[email protected]>
Reviewed-by: Jonathan Amsterdam <[email protected]>

Author: jamalc

content/static/css/stylesheet.css

@@ -1274,6 +1274,19 @@ pre {
   color: var(--gray-3);
   margin-top: -0.5rem;
 }
+@media only screen and (min-width: 64rem) {
+  .Documentation-toc {
+    columns: 2;
+    white-space: nowrap;
+  }
+}
+.Documentation-toc:empty {
+  display: none;
+}
+.Documentation-tocItem {
+  text-overflow: ellipsis;
+  overflow: hidden;
+}
 
 .Documentation-tocItem--constants,
 .Documentation-tocItem--funcsAndTypes,

internal/godoc/dochtml/dochtml.go

@@ -25,7 +25,9 @@ import (
 	"github.com/google/safehtml/legacyconversions"
 	"github.com/google/safehtml/template"
 	"github.com/google/safehtml/uncheckedconversions"
+	"golang.org/x/pkgsite/internal"
 	"golang.org/x/pkgsite/internal/derrors"
+	"golang.org/x/pkgsite/internal/experiment"
 	"golang.org/x/pkgsite/internal/godoc/dochtml/internal/render"
 	"golang.org/x/pkgsite/internal/godoc/internal/doc"
 )
@@ -193,6 +195,7 @@ func renderInfo(ctx context.Context, fset *token.FileSet, p *doc.Package, opt Re
 			return "/" + versionedPath
 		},
 		DisableHotlinking: true,
+		EnableCommandTOC:  experiment.IsActive(ctx, internal.ExperimentCommandTOC),
 	})
 
 	fileLink := func(name string) safehtml.HTML {

internal/godoc/dochtml/internal/render/linkify.go

@@ -63,6 +63,7 @@ var (
 type docData struct {
 	Elements          []docElement
 	DisablePermalinks bool
+	EnableCommandTOC  bool
 }
 
 type docElement struct {
@@ -112,7 +113,8 @@ func (r *Renderer) declHTML(doc string, decl ast.Decl, extractLinks bool) (out s
 				}
 			}
 		}
-		out.Doc = ExecuteToHTML(r.docTmpl, docData{Elements: els, DisablePermalinks: r.disablePermalinks})
+		out.Doc = ExecuteToHTML(r.docTmpl, docData{Elements: els,
+			DisablePermalinks: r.disablePermalinks, EnableCommandTOC: r.enableCommandTOC})
 	}
 	if decl != nil {
 		out.Decl = r.formatDeclHTML(decl, idr)

internal/godoc/dochtml/internal/render/render.go

@@ -36,6 +36,7 @@ type Renderer struct {
 	packageURL        func(string) string
 	disableHotlinking bool
 	disablePermalinks bool
+	enableCommandTOC  bool
 	ctx               context.Context
 	docTmpl           *template.Template
 	exampleTmpl       *template.Template
@@ -65,10 +66,29 @@ type Options struct {
 	//
 	// Only relevant for HTML formatting.
 	DisablePermalinks bool
+
+	// EnableCommandTOC turns on the table of contents for the overview section
+	// of command pages.
+	//
+	// Only relevant for HTML formatting.
+	EnableCommandTOC bool
 }
 
 // docDataTmpl renders documentation. It expects a docData.
 var docDataTmpl = template.Must(template.New("").Parse(`
+{{- if and .EnableCommandTOC .Elements -}}
+	<div role="navigation" aria-label="Table of Contents">
+		<ul class="Documentation-toc">
+			{{- range .Elements -}}
+				{{- if .IsHeading -}}
+					<li class="Documentation-tocItem">
+						<a href="#{{.ID}}">{{.Title}}</a>
+					</li>
+				{{- end -}}
+			{{- end -}}
+		</ul>
+	</div>
+{{- end -}}
 {{- range .Elements -}}
   {{- if .IsHeading -}}
     <h4 id="{{.ID}}">{{.Title}}
@@ -99,6 +119,7 @@ func New(ctx context.Context, fset *token.FileSet, pkg *doc.Package, opts *Optio
 	var packageURL func(string) string
 	var disableHotlinking bool
 	var disablePermalinks bool
+	var enableCommandTOC bool
 	if opts != nil {
 		if len(opts.RelatedPackages) > 0 {
 			others = opts.RelatedPackages
@@ -108,6 +129,7 @@ func New(ctx context.Context, fset *token.FileSet, pkg *doc.Package, opts *Optio
 		}
 		disableHotlinking = opts.DisableHotlinking
 		disablePermalinks = opts.DisablePermalinks
+		enableCommandTOC = opts.EnableCommandTOC
 	}
 	pids := newPackageIDs(pkg, others...)
 
@@ -117,6 +139,7 @@ func New(ctx context.Context, fset *token.FileSet, pkg *doc.Package, opts *Optio
 		packageURL:        packageURL,
 		disableHotlinking: disableHotlinking,
 		disablePermalinks: disablePermalinks,
+		enableCommandTOC:  enableCommandTOC,
 		docTmpl:           docDataTmpl,
 		exampleTmpl:       exampleTmpl,
 		ctx:               ctx,