render

Documentation

Overview

Package render formats Go documentation as HTML. It is an internal component that powers dochtml.

Index

• Variables
• func ConstOrVarSynopsis(valueSpec *ast.ValueSpec, fset *token.FileSet, tok token.Token, trailer string, ...) string
• func ExecuteToHTML(tmpl *template.Template, data any) safe.HTML
• func OneLineField(fset *token.FileSet, field *ast.Field, depth int) string
• func OneLineNodeDepth(fset *token.FileSet, node ast.Node, depth int) string
• func SafeGoID(s string) safe.Identifier
• func ValidateGoDottedExpr(s string)
• type Link
• type Options
• type Renderer
  • func New(ctx context.Context, fset *token.FileSet, pkg *doc.Package, opts *Options) *Renderer
  • func (r *Renderer) CodeHTML(ex *doc.Example) safehtml.HTML
  • func (r *Renderer) DeclHTML(doc string, decl ast.Decl) (out struct{ ... })
  • func (r *Renderer) DocHTML(doc string) safehtml.HTML
  • func (r *Renderer) DocHTMLExtractLinks(doc string) safehtml.HTML
  • func (r *Renderer) Links() []Link
  • func (r *Renderer) ShortSynopsis(n ast.Node) (string, error)
  • func (r *Renderer) Synopsis(n ast.Node) string

Variables

var LinkTemplate = template.Must(template.New("link").Parse(
	`<a {{with .Class}}class="{{.}}" {{end}}href="{{.Href}}">{{.Text}}</a>`))

Functions

func ConstOrVarSynopsis

func ConstOrVarSynopsis(valueSpec *ast.ValueSpec, fset *token.FileSet, tok token.Token,
	trailer string, i, depth int) string

func ExecuteToHTML

func ExecuteToHTML(tmpl *template.Template, data any) safe.HTML

func OneLineField

func OneLineField(fset *token.FileSet, field *ast.Field, depth int) string

OneLineField returns a one-line summary of the field.

func OneLineNodeDepth

func OneLineNodeDepth(fset *token.FileSet, node ast.Node, depth int) string

OneLineNodeDepth returns a one-line summary of the given input node. The depth specifies the current depth when traversing the AST and the function will stop traversing once depth reaches maxSynopsisNodeDepth.

func SafeGoID

func SafeGoID(s string) safe.Identifier

SafeGoID constructs a safe identifier from a Go symbol or dotted concatenation of symbols (e.g. "Time.Equal").

func ValidateGoDottedExpr

func ValidateGoDottedExpr(s string)

ValidateGoDottedExpr panics if s contains characters other than '.' plus the valid Go identifier characters.

Types

type Link

type Link struct {
	Href, Text string
	Class      string // class for "a" tag; optional
}

Link is the data passed to LinkTemplate.

type Options

type Options struct {
	// RelatedPackages is a list of related packages to use for hotlinking.
	// A recommended heuristic is to include all packages imported by the
	// given package, its tests, and its example tests.
	//
	// Only relevant for HTML formatting.
	RelatedPackages []*doc.Package

	// PackageURL is a function that given a package path,
	// returns a URL for navigating to the godoc for that package.
	//
	// Only relevant for HTML formatting.
	PackageURL func(pkgPath string) (url string)
}

type Renderer

type Renderer struct {
	// contains filtered or unexported fields
}

func New

func New(ctx context.Context, fset *token.FileSet, pkg *doc.Package, opts *Options) *Renderer

func (*Renderer) CodeHTML

func (r *Renderer) CodeHTML(ex *doc.Example) safehtml.HTML

CodeHTML formats example code. If the code is a single block statement, the outer braces are stripped and the code unindented. If the example code contains an output comment, that will stripped as well.

The code type must be *ast.File, *CommentedNode, []ast.Decl, []ast.Stmt or assignment-compatible to ast.Expr, ast.Decl, ast.Spec, or ast.Stmt.

This returns formatted HTML with:

<pre>                   element wrapping entire block
<span class="comment">  elements for every Go comment

CodeHTML is intended for use with example code snippets.

func (*Renderer) DeclHTML

func (r *Renderer) DeclHTML(doc string, decl ast.Decl) (out struct{ Doc, Decl safehtml.HTML })

DeclHTML formats the doc and decl and returns a tuple of strings corresponding to each input argument.

This formats documentation HTML according to the same rules as DocHTML.

This formats declaration HTML with:

<pre>                       element wrapping the entire declaration
<span id="X" data-kind="K"> elements for many top-level declarations
<span class="comment">      elements for every Go comment
<a href="XXX">              elements for URL hyperlinks

DeclHTML is intended for top-level package declarations.

func (*Renderer) DocHTML

func (r *Renderer) DocHTML(doc string) safehtml.HTML

DocHTML formats documentation text as HTML.

Each span of unindented non-blank lines is converted into a single paragraph. There is one exception to the rule: a span that consists of a single line, is followed by another paragraph span, begins with a capital letter, and contains no punctuation is formatted as a heading.

A span of indented lines is converted into a <pre> block, with the common indent prefix removed.

URLs in the comment text are converted into links. Any word that matches an exported top-level identifier in the package is automatically converted into a hyperlink to the declaration of that identifier.

This returns formatted HTML with:

<p>                elements for plain documentation text
<pre>              elements for preformatted text
<h3 id="hdr-XXX">  elements for headings with the "id" attribute
<a href="XXX">     elements for URL hyperlinks

DocHTML is intended for documentation for the package and examples.

func (*Renderer) DocHTMLExtractLinks

func (r *Renderer) DocHTMLExtractLinks(doc string) safehtml.HTML

DocHTMLExtractLinks is like DocHTML, but as a side-effect, the "Links" heading of doc is removed and its links are extracted.

func (*Renderer) Links

func (r *Renderer) Links() []Link

Links returns the links extracted by DocHTMLExtractLinks.

func (*Renderer) ShortSynopsis

func (r *Renderer) ShortSynopsis(n ast.Node) (string, error)

ShortSynopsis returns a very short, one-line summary of the given input node. It currently only supports *ast.FuncDecl nodes and will return a non-nil error otherwise.

func (*Renderer) Synopsis

func (r *Renderer) Synopsis(n ast.Node) string

Synopsis returns a one-line summary of the given input node.