dochtml

Documentation

Overview

Package dochtml renders Go package documentation into HTML.

This package and its API are under development (see golang.org/issue/39883). The plan is to iterate on the development internally for x/pkgsite needs first, before factoring it out somewhere non-internal where its API can no longer be easily modified.

Index

• Variables
• func GetSymbols(p *doc.Package, fset *token.FileSet) (_ []*internal.Symbol, err error)
• func LoadTemplates(fsys template.TrustedFS)
• func Templates() []*template.Template
• func WalkExamples(p *doc.Package, fn func(id string, ex *doc.Example))
• type ModuleInfo
• type Parts
  • func Render(ctx context.Context, fset *token.FileSet, p *doc.Package, opt RenderOptions) (_ *Parts, err error)
• type RenderOptions
• type TemplateData

Variables

var (
	// ErrTooLarge represents an error where the rendered documentation HTML
	// size exceeded the specified limit. See the RenderOptions.Limit field.
	ErrTooLarge = errors.New("rendered documentation HTML size exceeded the specified limit")
)

Functions

func GetSymbols

func GetSymbols(p *doc.Package, fset *token.FileSet) (_ []*internal.Symbol, err error)

GetSymbols renders package documentation HTML for the provided file set and package, in separate parts.

If any of the rendered documentation part HTML sizes exceeds the specified limit, an error with ErrTooLarge in its chain will be returned.

func LoadTemplates

func LoadTemplates(fsys template.TrustedFS)

LoadTemplates reads and parses the templates used to generate documentation.

func Templates

func Templates() []*template.Template

func WalkExamples

func WalkExamples(p *doc.Package, fn func(id string, ex *doc.Example))

WalkExamples calls fn for each Example in p, setting id to the name of the parent structure.

Types

type ModuleInfo

type ModuleInfo struct {
	ModulePath      string
	ResolvedVersion string
	// ModulePackages is the set of all full package paths in the module.
	ModulePackages map[string]bool
}

ModuleInfo contains all the information a package needs about the module it belongs to in order to render its documentation.

type Parts

type Parts struct {
	Body          safehtml.HTML // main body of doc
	Outline       safehtml.HTML // outline for large screens
	MobileOutline safehtml.HTML // outline for mobile
	Links         []render.Link // "Links" section of package doc
}

Parts contains HTML for each part of the documentation.

func Render

func Render(ctx context.Context, fset *token.FileSet, p *doc.Package, opt RenderOptions) (_ *Parts, err error)

Render renders package documentation HTML for the provided file set and package, in separate parts.

If any of the rendered documentation part HTML sizes exceeds the specified limit, an error with ErrTooLarge in its chain will be returned.

type RenderOptions

type RenderOptions struct {
	// FileLinkFunc optionally specifies a function that
	// returns a URL where file should be linked to.
	// file is the name component of a .go file in the package,
	// including the .go qualifier.
	// As a special case, FileLinkFunc may return the empty
	// string to indicate that a given file should not be linked.
	FileLinkFunc     func(file string) (url string)
	SourceLinkFunc   func(ast.Node) string
	SinceVersionFunc func(name string) string
	// ModInfo optionally specifies information about the module the package
	// belongs to in order to render module-related documentation.
	ModInfo          *ModuleInfo
	Limit            int64 // If zero, a default limit of 10 megabytes is used.
	BuildContext     internal.BuildContext
	FilterPackageURL func(string) string
}

RenderOptions are options for Render.

type TemplateData

type TemplateData struct {
	RootURL                    string
	Package                    *doc.Package
	Consts, Vars, Funcs, Types []*item
	Examples                   *examples
	NoteHeaders                map[string]noteHeader
}

TemplateData holds the data passed to the HTML templates in this package.