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 (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
Constants ¶
This section is empty.
Variables ¶
var LinkTemplate = template.Must(template.New("link").Parse(
`<a {{with .Class}}class="{{.}}" {{end}}href="{{.Href}}">{{.Text}}</a>`))
Functions ¶
func ConstOrVarSynopsis ¶
func OneLineField ¶
OneLineField returns a one-line summary of the field.
func OneLineNodeDepth ¶
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 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 (*Renderer) CodeHTML ¶
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 ¶
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 ¶
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 ¶
DocHTMLExtractLinks is like DocHTML, but as a side-effect, the "Links" heading of doc is removed and its links are extracted.
func (*Renderer) ShortSynopsis ¶
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.
Source Files