Command github.com/matjam/bunyip/cmd/bunyip-docs

cmd/bunyip-docs

Command bunyip-docs renders the module's documentation as a static website: guides written in Markdown, a walkthrough of every example program, every package's godoc with its examples, a symbol search, and links back to the source on GitHub.

CGO_ENABLED=0 go run ./cmd/bunyip-docs -out site

Run from the module root. The -out flag defaults to site; -guides and -examples default to docs/guides and docs/examples. The -base flag defaults to https://matjam.github.io/bunyip/ and controls published links in llms.txt and llms-full.txt. Generation writes local files; publishing is a separate step handled by the repository's Docs workflow.

The example walkthroughs are the Markdown files in docs/examples, one per directory under examples, with the same front matter as a guide plus an example key naming the directory. A screenshot beside a walkthrough, docs/examples/<name>.png, is shown at the top of its page. The pages of examples/ are not rendered as packages; the walkthroughs document them instead.

Index

type Example
type Func
type Group
type Guide
type GuideGroup
type Package
- func (p *Package) MarkdownURL() string
type Program
type Site
type Type
type Value

Types

type Example source

type Example struct {
	Name, Suffix string
	Doc          template.HTML
	DocMD        string
	Code         template.HTML
	CodeText     string
	Output       string
}

Example is a runnable example with its code and output.

type Func source

type Func struct {
	Name, ID string
	Doc      template.HTML
	DocMD    string
	Decl     template.HTML
	DeclText string
	Src      string
	Examples []*Example
}

Func is a function or method.

type Group source

type Group struct {
	Title    string
	Packages []*Package
}

Group is a sidebar section of packages.

type Guide source

type Guide struct {
	Title, Slug, Summary, Group string
	Order                       int
	Body                        template.HTML
	Markdown                    string // the source, with the front matter replaced by a heading
	Headings                    []heading
}

Guide is one Markdown page.

type GuideGroup source

type GuideGroup struct {
	Title  string
	Guides []*Guide
}

GuideGroup is a sidebar section of guides.

type Package source

type Package struct {
	Name, ImportPath, Rel, URL, Synopsis string
	IsCommand                            bool
	Doc                                  template.HTML
	DocMD                                string // the package comment as Markdown
	Consts, Vars                         []*Value
	Funcs                                []*Func
	Types                                []*Type
	Examples                             []*Example
	Files                                []string
}

Package is one rendered package.

MarkdownURL source

func (p *Package) MarkdownURL() string

MarkdownURL is the package's Markdown page, beside the HTML one.

type Program source

type Program struct {
	Title, Name, Summary string
	Body                 template.HTML
	Markdown             string // the source, with the front matter replaced by a heading
	Headings             []heading
	Files                []string // the .go files of examples/<name>
	Shot                 bool     // docs/examples/<name>.png exists
	Missing              bool     // no walkthrough is written yet
}

Program is one example program: the walkthrough in docs/examples, the screenshot beside it, and the links to the source. An example with no walkthrough yet is still listed, with Missing set.

MarkdownURL source

func (p *Program) MarkdownURL() string

MarkdownURL is the walkthrough's Markdown page, beside the HTML one.

SourceURL source

func (p *Program) SourceURL() string

SourceURL is the example's directory on GitHub.

URL source

func (p *Program) URL() string

URL is the walkthrough's page, relative to the site root.

type Site source

type Site struct {
	Guides      []*Guide
	GuideGroups []GuideGroup
	Programs    []*Program
	Packages    []*Package
	Groups      []Group
	Base        string // the published URL, with a trailing slash
	// contains filtered or unexported fields
}

Site is everything rendered.

type Type source

type Type struct {
	Name         string
	Doc          template.HTML
	DocMD        string
	Decl         template.HTML
	DeclText     string
	Src          string
	Consts, Vars []*Value
	Funcs        []*Func // constructors
	Methods      []*Func
	Examples     []*Example
	Members      []symbol // exported fields and explicitly declared interface methods
}

Type is a type with its associated declarations.

type Value source

type Value struct {
	Names    []string
	Doc      template.HTML
	DocMD    string
	Decl     template.HTML
	DeclText string
	Src      string
}

Value is a const or var block.

Source files

docs_test.go generator_test.go links.go main.go markdown.go site_validation_test.go symbols.go templates.go