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  template.HTML

}

// FuncData wraps godoc.FuncDoc for templates.

type FuncData struct {

	Name       string

	Doc        template.HTML

	Decl       template.HTML

	Recv       string

	SourceFile string

	SourceLine int

}

// TypeData wraps godoc.TypeDoc for templates.

type TypeData struct {

	Name       string

	Doc        template.HTML

	Decl       template.HTML

	Consts     []ValueData

	Vars       []ValueData

	Funcs      []FuncData

	Methods    []FuncData

	SourceFile string

	SourceLine int

}

// 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) {

	funcs := template.FuncMap{

		"hasPrefix": strings.HasPrefix,

	}

	base, err := template.New("base").Funcs(funcs).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 symbol map for cross-referencing in declarations.

		symbols := make(map[string]string)

		for _, t := range doc.Types {

			symbols[t.Name] = "#" + t.Name

			for _, c := range t.Consts {

				for _, name := range c.Names {

					symbols[name] = "#" + name

				}

			}

			for _, v := range t.Vars {

				for _, name := range v.Names {

					symbols[name] = "#" + name

				}

			}

			for _, f := range t.Funcs {

				symbols[f.Name] = "#" + f.Name

			}

		}

		for _, f := range doc.Funcs {

			symbols[f.Name] = "#" + f.Name

		}

		for _, c := range doc.Consts {

			for _, name := range c.Names {

				symbols[name] = "#" + name

			}

		}

		for _, v := range doc.Vars {

			for _, name := range v.Names {

				symbols[name] = "#" + name

			}

		}

		// 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...)

		// Build import link map: alias → base doc URL.

		// Local imports (under our host) link to our own docs.

		// External imports link to pkg.go.dev.

		importLinks := make(map[string]string, len(doc.Imports))

		for alias, path := range doc.Imports {

			if strings.HasPrefix(path, host+"/") {

				// Local module: link to our doc page.

				// e.g., "go.bigb.es/curator/internal/config" → "/curator/internal/config" (TODO: version?)

				importLinks[alias] = "/" + strings.TrimPrefix(path, host+"/")

			} else {

				importLinks[alias] = "https://pkg.go.dev/" + path

			}

		}

		// Convert godoc types to template types.

		imports := importLinks

		for _, c := range doc.Consts {

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

		}

		for _, v := range doc.Vars {

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

		}

		for _, f := range doc.Funcs {

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

		}

		for _, t := range doc.Types {

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

		}

	}

	return data

}

func hlDecl(s string, symbols map[string]string, imports map[string]string) template.HTML {

	return template.HTML(godoc.HighlightDeclLinked(s, symbols, imports))

}

func convertValue(v godoc.ValueDoc, symbols, imports map[string]string) ValueData {

	return ValueData{

		Names: v.Names,

		Doc:   template.HTML(v.Doc),

		Decl:  hlDecl(v.Decl, symbols, imports),

	}

}

func convertFunc(f godoc.FuncDoc, symbols, imports map[string]string) FuncData {

	return FuncData{

		Name:       f.Name,

		Doc:        template.HTML(f.Doc),

		Decl:       hlDecl(f.Decl, symbols, imports),

		Recv:       f.Recv,

		SourceFile: f.SourceFile,

		SourceLine: f.SourceLine,

	}

}

func convertType(t godoc.TypeDoc, symbols, imports map[string]string) TypeData {

	td := TypeData{

		Name:       t.Name,

		Doc:        template.HTML(t.Doc),

		Decl:       hlDecl(t.Decl, symbols, imports),

		SourceFile: t.SourceFile,

		SourceLine: t.SourceLine,

	}

	for _, c := range t.Consts {

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

	}

	for _, v := range t.Vars {

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

	}

	for _, f := range t.Funcs {

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

	}

	for _, m := range t.Methods {

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

	}

	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))

}