pkgsite: Index | Files

package render

import ""

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


Package Files

idents.go linkify.go render.go short_synopsis.go synopsis.go


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

func ExecuteToHTML Uses

func ExecuteToHTML(tmpl *template.Template, data interface{}) safehtml.HTML

func SafeGoID Uses

func SafeGoID(s string) safehtml.Identifier

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

func ValidateGoDottedExpr Uses

func ValidateGoDottedExpr(s string)

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

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

Link is the data passed to LinkTemplate.

type Options Uses

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)

    // DisableHotlinking turns off hotlinking behavior.
    // Only relevant for HTML formatting.
    DisableHotlinking bool

    // DisablePermalinks turns off inserting of '¶' permalinks in headings.
    // Only relevant for HTML formatting.
    DisablePermalinks bool

type Renderer Uses

type Renderer struct {
    // contains filtered or unexported fields

func New Uses

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

func (*Renderer) CodeHTML Uses

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 Uses

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 Uses

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 (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 (r *Renderer) Links() []Link

Links returns the links extracted by DocHTMLExtractLinks.

func (*Renderer) ShortSynopsis Uses

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 Uses

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

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

Package render imports 19 packages (graph) and is imported by 2 packages. Updated 2021-01-16. Refresh now. Tools for package owners.