render.go

package dochtml

import (

	"embed"

	"html/template"

	"io"

	"io/fs"

	"net/http"

	"sort"

	"strings"

	"go.bigb.es/curator/internal/godoc"

)

//go:embed templates/* static/*

var content embed.FS

// StaticFS returns the embedded static assets filesystem.

func StaticFS() http.FileSystem {

	sub, _ := fs.Sub(content, "static")

	return http.FS(sub)

}

// IndexEntry represents an entry in the package index.

type IndexEntry struct {

	Anchor   string

	Text     string

	Children []IndexEntry // constructors and methods (for types)

}

// ModulePageData is the template data for module/package pages.

type ModulePageData struct {

	Host         string

	ImportPrefix string

	ModuleName   string

	VCS          string

	Repo         string

	Version      string

	SubPath      string

	Versions     []string

	// Package doc fields.

	Doc         template.HTML

	Synopsis    string

	PackageName string

	Index       []IndexEntry

	Consts      []ValueData

	Vars        []ValueData

	Funcs       []FuncData

	Types       []TypeData

	SubPackages []godoc.SubPkgSummary

	SourceFiles []string

}

// ValueData wraps godoc.ValueDoc for templates.

type ValueData struct {

	Names []string

	Doc   template.HTML

	Decl  string

}

// FuncData wraps godoc.FuncDoc for templates.

type FuncData struct {

	Name string

	Doc  template.HTML

	Decl string

	Recv string

}

// TypeData wraps godoc.TypeDoc for templates.

type TypeData struct {

	Name    string

	Doc     template.HTML

	Decl    string

	Consts  []ValueData

	Vars    []ValueData

	Funcs   []FuncData

	Methods []FuncData

}

// SourcePageData is the template data for source file view.

type SourcePageData struct {

	Host              string

	ImportPrefix      string

	ModuleName        string

	VCS               string

	Repo              string

	Version           string

	SubPath           string

	FileName          string

	HighlightedSource template.HTML

	SourceFiles       []string

}

// VersionsPageData is the template data for the versions list.

type VersionsPageData struct {

	Host           string

	ImportPrefix   string

	ModuleName     string

	VCS            string

	Repo           string

	Versions       []string

	CurrentVersion string

}

// Renderer handles HTML rendering of documentation pages.

type Renderer struct {

	moduleTmpl   *template.Template

	sourceTmpl   *template.Template

	versionsTmpl *template.Template

}

// NewRenderer creates a renderer with parsed templates.

func NewRenderer() (*Renderer, error) {

	base, err := template.New("base").Parse(mustRead("templates/base.html"))

	if err != nil {

		return nil, err

	}

	moduleTmpl, err := template.Must(base.Clone()).Parse(mustRead("templates/module.html"))

	if err != nil {

		return nil, err

	}

	sourceTmpl, err := template.Must(base.Clone()).Parse(mustRead("templates/source.html"))

	if err != nil {

		return nil, err

	}

	versionsTmpl, err := template.Must(base.Clone()).Parse(mustRead("templates/versions.html"))

	if err != nil {

		return nil, err

	}

	return &Renderer{

		moduleTmpl:   moduleTmpl,

		sourceTmpl:   sourceTmpl,

		versionsTmpl: versionsTmpl,

	}, nil

}

// RenderModule renders a module/package documentation page.

func (r *Renderer) RenderModule(w io.Writer, data *ModulePageData) error {

	return r.moduleTmpl.Execute(w, data)

}

// RenderSource renders a source code view page.

func (r *Renderer) RenderSource(w io.Writer, data *SourcePageData) error {

	return r.sourceTmpl.Execute(w, data)

}

// RenderVersions renders a version list page.

func (r *Renderer) RenderVersions(w io.Writer, data *VersionsPageData) error {

	return r.versionsTmpl.Execute(w, data)

}

// BuildModulePageData creates template data from a PackageDoc.

func BuildModulePageData(host, modName, version, subpath, vcs, repo string, doc *godoc.PackageDoc, versions []string, subPkgs []godoc.SubPkgSummary) *ModulePageData {

	data := &ModulePageData{

		Host:         host,

		ImportPrefix: host + "/" + modName,

		ModuleName:   modName,

		VCS:          vcs,

		Repo:         repo,

		Version:      version,

		SubPath:      subpath,

		Versions:     versions,

		SubPackages:  subPkgs,

	}

	if doc != nil {

		data.Doc = template.HTML(doc.Doc)

		data.Synopsis = doc.Synopsis

		data.PackageName = doc.Name

		data.SourceFiles = doc.Files

		// Build hierarchical index: funcs sorted, then types sorted

		// with constructors and methods as children.

		var funcIndex []IndexEntry

		for _, f := range doc.Funcs {

			funcIndex = append(funcIndex, IndexEntry{

				Anchor: f.Name,

				Text:   f.ShortDecl,

			})

		}

		sort.Slice(funcIndex, func(i, j int) bool {

			return funcIndex[i].Text < funcIndex[j].Text

		})

		var typeIndex []IndexEntry

		for _, t := range doc.Types {

			entry := IndexEntry{

				Anchor: t.Name,

				Text:   "type " + t.Name,

			}

			// Constructors (sorted).

			var constructors []IndexEntry

			for _, f := range t.Funcs {

				constructors = append(constructors, IndexEntry{

					Anchor: f.Name,

					Text:   f.ShortDecl,

				})

			}

			sort.Slice(constructors, func(i, j int) bool {

				return constructors[i].Text < constructors[j].Text

			})

			entry.Children = append(entry.Children, constructors...)

			// Type-associated constants (sorted).

			var consts []IndexEntry

			for _, c := range t.Consts {

				for _, name := range c.Names {

					consts = append(consts, IndexEntry{

						Anchor: name,

						Text:   "const " + name,

					})

				}

			}

			for _, v := range t.Vars {

				for _, name := range v.Names {

					consts = append(consts, IndexEntry{

						Anchor: name,

						Text:   "var " + name,

					})

				}

			}

			sort.Slice(consts, func(i, j int) bool {

				return consts[i].Text < consts[j].Text

			})

			entry.Children = append(entry.Children, consts...)

			// Methods (sorted).

			var methods []IndexEntry

			for _, m := range t.Methods {

				methods = append(methods, IndexEntry{

					Anchor: t.Name + "." + m.Name,

					Text:   m.ShortDecl,

				})

			}

			sort.Slice(methods, func(i, j int) bool {

				return methods[i].Text < methods[j].Text

			})

			entry.Children = append(entry.Children, methods...)

			typeIndex = append(typeIndex, entry)

		}

		sort.Slice(typeIndex, func(i, j int) bool {

			return typeIndex[i].Text < typeIndex[j].Text

		})

		data.Index = append(funcIndex, typeIndex...)

		// Convert godoc types to template types.

		for _, c := range doc.Consts {

			data.Consts = append(data.Consts, convertValue(c))

		}

		for _, v := range doc.Vars {

			data.Vars = append(data.Vars, convertValue(v))

		}

		for _, f := range doc.Funcs {

			data.Funcs = append(data.Funcs, convertFunc(f))

		}

		for _, t := range doc.Types {

			data.Types = append(data.Types, convertType(t))

		}

	}

	return data

}

func convertValue(v godoc.ValueDoc) ValueData {

	return ValueData{

		Names: v.Names,

		Doc:   template.HTML(v.Doc),

		Decl:  v.Decl,

	}

}

func convertFunc(f godoc.FuncDoc) FuncData {

	return FuncData{

		Name: f.Name,

		Doc:  template.HTML(f.Doc),

		Decl: f.Decl,

		Recv: f.Recv,

	}

}

func convertType(t godoc.TypeDoc) TypeData {

	td := TypeData{

		Name: t.Name,

		Doc:  template.HTML(t.Doc),

		Decl: t.Decl,

	}

	for _, c := range t.Consts {

		td.Consts = append(td.Consts, convertValue(c))

	}

	for _, v := range t.Vars {

		td.Vars = append(td.Vars, convertValue(v))

	}

	for _, f := range t.Funcs {

		td.Funcs = append(td.Funcs, convertFunc(f))

	}

	for _, m := range t.Methods {

		td.Methods = append(td.Methods, convertFunc(m))

	}

	return td

}

// TrustedHTML converts a string to template.HTML for pre-sanitized content.

func TrustedHTML(s string) template.HTML {

	return template.HTML(s)

}

func mustRead(name string) string {

	data, err := content.ReadFile(name)

	if err != nil {

		panic("dochtml: " + err.Error())

	}

	return strings.TrimSpace(string(data))

}