Package: golang.org/x/pkgsite/internal/godoc/dochtml

package dochtml Import Path golang.org/x/pkgsite/internal/godoc/dochtml (on go.dev) Dependency Relation imports 21 packages, and imported by 3 packages

Involved Source Files d➜ dochtml.go 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. io.go symbol.go template.go

Package-Level Type Names (total 9, in which 3 are exported)

/* sort exporteds by: alphabet | popularity */

type ModuleInfo (struct) ModuleInfo contains all the information a package needs about the module it belongs to in order to render its documentation. Fields (total 3, all are exported) ModulePackages map[string]bool ModulePackages is the set of all full package paths in the module. ModulePath string ResolvedVersion string As Inputs Of (at least 7, in which 2 are exported) func golang.org/x/pkgsite/internal/godoc.(*Package).DocInfo(ctx context.Context, innerPath string, sourceInfo *source.Info, modInfo *godoc.ModuleInfo) (synopsis string, imports []string, api []*internal.Symbol, err error) func golang.org/x/pkgsite/internal/godoc.(*Package).Render(ctx context.Context, innerPath string, sourceInfo *source.Info, modInfo *godoc.ModuleInfo, nameToVersion map[string]string) (_ *Parts, err error) /* 5+ unexporteds ... *//* 5+ unexporteds: */ func versionedPkgPath(pkgPath string, modInfo *ModuleInfo) string func golang.org/x/pkgsite/internal/godoc.(*Package).docPackage(innerPath string, modInfo *godoc.ModuleInfo) (_ *doc.Package, err error) func golang.org/x/pkgsite/internal/godoc.(*Package).renderOptions(innerPath string, sourceInfo *source.Info, modInfo *godoc.ModuleInfo, nameToVersion map[string]string) RenderOptions func golang.org/x/pkgsite/internal/fetch.loadPackage(ctx context.Context, zipGoFiles []*zip.File, innerPath string, sourceInfo *source.Info, modInfo *godoc.ModuleInfo) (_ *fetch.goPackage, err error) func golang.org/x/pkgsite/internal/fetch.loadPackageForBuildContext(ctx context.Context, files map[string][]byte, innerPath string, sourceInfo *source.Info, modInfo *godoc.ModuleInfo) (name string, imports []string, synopsis string, source []byte, api []*internal.Symbol, err error)

type Parts (struct) Parts contains HTML for each part of the documentation. Fields (total 4, all are exported) Body safehtml.HTML // main body of doc Links []render.Link // "Links" section of package doc MobileOutline safehtml.HTML // outline for mobile Outline safehtml.HTML // outline for large screens As Outputs Of (at least 5, in which 3 are exported) func Render(ctx context.Context, fset *token.FileSet, p *doc.Package, opt RenderOptions) (_ *Parts, err error) func golang.org/x/pkgsite/internal/godoc.RenderFromUnit(ctx context.Context, u *internal.Unit) (_ *Parts, err error) func golang.org/x/pkgsite/internal/godoc.(*Package).Render(ctx context.Context, innerPath string, sourceInfo *source.Info, modInfo *godoc.ModuleInfo, nameToVersion map[string]string) (_ *Parts, err error) /* 2+ unexporteds ... *//* 2+ unexporteds: */ func golang.org/x/pkgsite/internal/frontend.getHTML(ctx context.Context, u *internal.Unit, docPkg *godoc.Package, nameToVersion map[string]string) (_ *Parts, err error) func golang.org/x/pkgsite/internal/frontend.renderDocParts(ctx context.Context, u *internal.Unit, docPkg *godoc.Package, nameToVersion map[string]string) (_ *Parts, err error)

type RenderOptions (struct) RenderOptions are options for Render. Fields (total 5, all are exported) FileLinkFunc func(file string) (url string) 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. Limit int64 // If zero, a default limit of 10 megabytes is used. ModInfo *ModuleInfo ModInfo optionally specifies information about the module the package belongs to in order to render module-related documentation. SinceVersionFunc func(name string) string SourceLinkFunc func(ast.Node) string As Outputs Of (at least one unexported) /* at least one unexported ... *//* at least one unexported: */ func golang.org/x/pkgsite/internal/godoc.(*Package).renderOptions(innerPath string, sourceInfo *source.Info, modInfo *godoc.ModuleInfo, nameToVersion map[string]string) RenderOptions As Inputs Of (at least 2, in which 1 are exported) func Render(ctx context.Context, fset *token.FileSet, p *doc.Package, opt RenderOptions) (_ *Parts, err error) /* at least one unexported ... *//* at least one unexported: */ func renderInfo(ctx context.Context, fset *token.FileSet, p *doc.Package, opt RenderOptions) (map[string]interface{}, templateData, func() []render.Link)

/* 6 unexporteds ... *//* 6 unexporteds: */

type example (struct) example is an internal representation of a single example. Fields (total 12, all are exported) Example *doc.Example Example.Comments []*ast.CommentGroup Example.Doc string // example function doc string Example.EmptyOutput bool // expect empty output Example.Name string // name of the item being exemplified (including optional suffix) Example.Order int // original source code order Example.Output string // expected output Example.Play *ast.File // a whole program version of the example Example.Unordered bool ID safehtml.Identifier // ID of example ParentID string // ID of top-level declaration this example is attached to Suffix string // optional suffix name in title case Methods (only one, which is exported) (*T) Code() interface{} Code returns an printer.CommentedNode if ex.Comments is non-nil, otherwise it returns ex.Code as is. As Inputs Of (at least 3, none are exported) /* 3+ unexporteds ... *//* 3+ unexporteds: */ func funcsToItems(fs []*doc.Func, hclass, typeName string, exmap map[string][]*example) []*item func packageToItems(p *doc.Package, exmap map[string][]*example) (consts, vars, funcs, types []*item) func typeToItem(t *doc.Type, exmap map[string][]*example) *item

type examples (struct) examples is an internal representation of all package examples. Fields (total 2, both are exported) List []*example // sorted by ParentID Map map[string][]*example // keyed by top-level ID (e.g., "NewRing" or "PubSub.Receive") or empty string for package examples As Outputs Of (at least one unexported) /* at least one unexported ... *//* at least one unexported: */ func collectExamples(p *doc.Package) *examples

type item (struct) An item is rendered as one piece of documentation. It is essentially a union of the Value, Type and Func types from internal/doc, along with additional information for HTML rendering, like class names. Fields (total 13, all are exported) Consts []*item // for types Decl ast.Decl // GenDecl for consts, vars and types; FuncDecl for functions Doc string Examples []*example // for types and functions; empty for vars and consts FullName string // for methods, the type name + "." + Name; else same as Name Funcs []*item // for types HeaderClass string // class for header HeaderStart string // text of header, before source link IsDeprecated bool Kind string HTML-specific values, for types and functions // for data-kind attribute Methods []*item // for types Name string // for types and functions; empty for consts and vars Vars []*item // for types As Outputs Of (at least 5, none are exported) /* 5+ unexporteds ... *//* 5+ unexporteds: */ func funcsToItems(fs []*doc.Func, hclass, typeName string, exmap map[string][]*example) []*item func packageToItems(p *doc.Package, exmap map[string][]*example) (consts, vars, funcs, types []*item) func typeToItem(t *doc.Type, exmap map[string][]*example) *item func valuesToItems(vs []*doc.Value) []*item func valueToItem(v *doc.Value) *item

type limitBuffer (struct) limitBuffer is designed to apply a limit on the number of bytes that are allowed to be written to a *bytes.Buffer. As long as Remain is a non-negative value, writes to limitBuffer are passed through to the underlying buffer B, decreasing Remain by the number of bytes written. If more than Remain bytes have been attempted to be written to B, Remain becomes a negative value, and limitBuffer.Write starts to always return io.ErrShortWrite without writing to B. Fields (total 2, both are exported) B *bytes.Buffer // Underlying buffer. Remain int64 // Until writes fail. Negative value means went beyond limit. Methods (only one, which is exported) (*T) Write(p []byte) (n int, err error) Write implements io.Writer. Implements (at least 3, all are exported) *T : github.com/go-git/go-git/v5/plumbing/protocol/packp/sideband.Progress *T : github.com/jbenet/go-context/io.Writer *T : io.Writer

type noteHeader (struct) noteHeader contains informations the template needs to render the note related HTML tags in documentation page. Fields (total 2, both are exported) Label string SafeIdentifier safehtml.Identifier As Outputs Of (at least one unexported) /* at least one unexported ... *//* at least one unexported: */ func buildNoteHeaders(notes map[string][]*doc.Note) map[string]noteHeader

type templateData (struct) templateData holds the data passed to the HTML templates in this package. Fields (total 8, all are exported) Consts []*item Examples *examples Funcs []*item NoteHeaders map[string]noteHeader Package *doc.Package RootURL string Types []*item Vars []*item As Outputs Of (at least one unexported) /* at least one unexported ... *//* at least one unexported: */ func renderInfo(ctx context.Context, fset *token.FileSet, p *doc.Package, opt RenderOptions) (map[string]interface{}, templateData, func() []render.Link)

Package-Level Functions (total 26, in which 4 are exported)

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(dir template.TrustedSource) LoadTemplates reads and parses the templates used to generate documentation.

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.

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.

/* 22 unexporteds ... *//* 22 unexporteds: */

func buildNoteHeaders(notes map[string][]*doc.Note) map[string]noteHeader buildNoteHeaders constructs note headers from note markers. It returns a map from each marker to its corresponding noteHeader.

func collectExamples(p *doc.Package) *examples collectExamples extracts examples from p into the internal examples representation.

func constants(consts []*doc.Value) []*internal.Symbol

func constantsForType(t *doc.Type) []*internal.SymbolMeta

func docIsEmpty(p *doc.Package) bool

func exampleID(id, suffix string) safehtml.Identifier

func executeToHTMLWithLimit(tmpl *template.Template, data interface{}, limit int64) (safehtml.HTML, error) executeToHTMLWithLimit executes tmpl on data and returns the result as a safehtml.HTML. It returns an error if the size of the result exceeds limit.

func fieldsForType(typName string, spec *ast.TypeSpec, fset *token.FileSet) []*internal.SymbolMeta

func funcsToItems(fs []*doc.Func, hclass, typeName string, exmap map[string][]*example) []*item

func functions(p *doc.Package, fset *token.FileSet) []*internal.Symbol

func functionsForType(t *doc.Type, fset *token.FileSet) []*internal.SymbolMeta

func linkHTML(name, url, class string) safehtml.HTML linkHTML returns an HTML-formatted name linked to the given URL. The class argument is the class of the 'a' tag. If url is the empty string, the name is not linked.

func methodsForType(t *doc.Type, spec *ast.TypeSpec, fset *token.FileSet) ([]*internal.SymbolMeta, error)

func packageToItems(p *doc.Package, exmap map[string][]*example) (consts, vars, funcs, types []*item)

func renderInfo(ctx context.Context, fset *token.FileSet, p *doc.Package, opt RenderOptions) (map[string]interface{}, templateData, func() []render.Link) renderInfo returns the functions and data needed to render the doc.

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

func typeToItem(t *doc.Type, exmap map[string][]*example) *item

func valuesToItems(vs []*doc.Value) []*item

func valueToItem(v *doc.Value) *item

func variables(vars []*doc.Value, fset *token.FileSet) (_ []*internal.Symbol, err error)

func variablesForType(t *doc.Type, fset *token.FileSet) (_ []*internal.SymbolMeta, err error)

func versionedPkgPath(pkgPath string, modInfo *ModuleInfo) string versionedPkgPath transforms package paths to contain the same version as the current module if the package belongs to the module. As a special case, versionedPkgPath will not add versions to standard library packages.

Package-Level Variables (total 6, in which 1 are exported)

var ErrTooLarge error ErrTooLarge represents an error where the rendered documentation HTML size exceeded the specified limit. See the RenderOptions.Limit field.

/* 5 unexporteds ... *//* 5 unexporteds: */

var bodyTemplate *template.Template TODO(golang.org/issue/5060): finalize URL scheme and design for notes, then it becomes more viable to factor out inline CSS style.

var loadOnce sync.Once

var outlineTemplate *template.Template TODO(golang.org/issue/5060): finalize URL scheme and design for notes, then it becomes more viable to factor out inline CSS style.

var sidenavTemplate *template.Template TODO(golang.org/issue/5060): finalize URL scheme and design for notes, then it becomes more viable to factor out inline CSS style.

var tmpl map[string]interface{}