package html

import "go.abhg.dev/doc2go/internal/html"

Package html renders HTML from godoc.Package.

Index

Constants

const StaticDir = "_"

StaticDir is the name of the directory in the output where static files are stored.

Types

type Breadcrumb struct {
	// Text for the crumb.
	Text string

	// Path to the crumb from the root of the output.
	Path string
}

Breadcrumb holds information about parents of a page so that we can leave a trail up for navigation.

type CommentDocPrinter

type CommentDocPrinter struct{ comment.Printer }

CommentDocPrinter is a DocPrinter built from a comment.Printer.

func (*CommentDocPrinter) WithHeadingLevel

func (dp *CommentDocPrinter) WithHeadingLevel(lvl int) DocPrinter

WithHeadingLevel returns a copy of this DocPrinter that will generate headers at the specified level.

type DocPrinter

type DocPrinter interface {
	HTML(*comment.Doc) []byte
	WithHeadingLevel(int) DocPrinter
}

DocPrinter formats godoc comments as HTML.

type Highlighter

type Highlighter interface {
	Highlight(*highlight.Code) string
	WriteCSS(io.Writer) error
}

Highlighter renders Go code into HTML.

type PackageIndex

type PackageIndex struct {
	// Path to this package index.
	Path string

	// Number of levels under output directory
	// that this package index is being generated for.
	//
	// 0 means it's being written to the output directory.
	// 1 means it's being written to a subdirectory of the output directory.
	SubDirDepth int

	NumChildren int
	Subpackages []Subpackage
	Breadcrumbs []Breadcrumb
}

PackageIndex holds information about a package listing.

func (*PackageIndex) Basename

func (idx *PackageIndex) Basename() string

Basename is the last component of this directory's path, or if it's the top level directory, an empty string.

func (*PackageIndex) IsInternal

func (idx *PackageIndex) IsInternal() bool

IsInternal reports whether packages under this index should be considered internal to some other package.

type PackageInfo

type PackageInfo struct {
	// Parsed package documentation information.
	*godoc.Package

	NumChildren int
	Subpackages []Subpackage
	Breadcrumbs []Breadcrumb

	SubDirDepth int
	PkgVersion  string

	// DocPrinter specifies how to render godoc comments.
	DocPrinter DocPrinter
}

PackageInfo specifies the package that should be rendered.

func (*PackageInfo) Basename

func (b *PackageInfo) Basename() string

Basename is the last component of this package's path.

func (*PackageInfo) IsInternal

func (b *PackageInfo) IsInternal() bool

IsInternal reports whether this package should be considered internal to some other package.

type Renderer

type Renderer struct {
	// Path to the home page of the generated site.
	Home string

	// Whether we're in embedded mode.
	// In this mode, output will only contain the documentation output
	// and will not generate complete, stylized HTML pages.
	Embedded bool

	// Internal specifies whether directory listings
	// should include internal packages.
	Internal bool

	// FrontMatter to include at the top of each file, if any.
	FrontMatter *ttemplate.Template

	// Highlighter renders code blocks into HTML.
	Highlighter Highlighter

	// NormalizeRelativePath is an optional function that
	// normalizes relative paths printed in the generated HTML.
	NormalizeRelativePath func(string) string

	// Pagefind specifies whether we have enabled client-side search with
	// pagefind.
	Pagefind bool
}

Renderer renders components into HTML.

func (*Renderer) RenderPackage

func (r *Renderer) RenderPackage(w io.Writer, info *PackageInfo) error

RenderPackage renders the documentation for a single Go package. It does not include subpackage information.

func (*Renderer) RenderPackageIndex

func (r *Renderer) RenderPackageIndex(w io.Writer, pidx *PackageIndex) error

RenderPackageIndex renders the list of descendants for a package as HTML.

func (*Renderer) RenderSiteIndex

func (r *Renderer) RenderSiteIndex(w io.Writer, sidx *SiteIndex) error

RenderSiteIndex renders the list of sub-sites as HTML.

func (*Renderer) WriteStatic

func (r *Renderer) WriteStatic(dir string) error

WriteStatic dumps the contents of static/ into the given directory.

This is a no-op if the renderer is running in embedded mode.

type SiteIndex

type SiteIndex struct {
	// Path will be empty unless -home was used.
	Path string

	Sites []string
}

SiteIndex holds information about the root-level site list. It's used when the -subdir flag is used to generate the top-level index of the various sub-sites.

type Subpackage

type Subpackage struct {
	// RelativePath is the path to the subpackage
	// relative to the package it's a subpackage of.
	RelativePath string

	// Synopsis is a short, one-sentence summary
	// extracted from the package's documentation.
	Synopsis string
}

Subpackage is a descendant of a Go package.

This is typically a direct descendant, but it may be a couple levels deeper if there are no intermediate Go packages. For example, foo/internal/bar may be a descendant of foo/ if internal is not a Go package.