# cmd/bunyip-docs

`import "github.com/matjam/bunyip/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/](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.

## Types

<a id="Example"></a>

<a id="Example.Name"></a>

<a id="Example.Suffix"></a>

<a id="Example.Doc"></a>

<a id="Example.DocMD"></a>

<a id="Example.Code"></a>

<a id="Example.CodeText"></a>

<a id="Example.Output"></a>

### Example

```go
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.

<a id="Func"></a>

<a id="Func.Name"></a>

<a id="Func.ID"></a>

<a id="Func.Doc"></a>

<a id="Func.DocMD"></a>

<a id="Func.Decl"></a>

<a id="Func.DeclText"></a>

<a id="Func.Src"></a>

<a id="Func.Examples"></a>

### Func

```go
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.

<a id="Group"></a>

<a id="Group.Title"></a>

<a id="Group.Packages"></a>

### Group

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

Group is a sidebar section of packages.

<a id="Guide"></a>

<a id="Guide.Title"></a>

<a id="Guide.Slug"></a>

<a id="Guide.Summary"></a>

<a id="Guide.Group"></a>

<a id="Guide.Order"></a>

<a id="Guide.Body"></a>

<a id="Guide.Markdown"></a>

<a id="Guide.Headings"></a>

### Guide

```go
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.

<a id="GuideGroup"></a>

<a id="GuideGroup.Title"></a>

<a id="GuideGroup.Guides"></a>

### GuideGroup

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

GuideGroup is a sidebar section of guides.

<a id="Package"></a>

<a id="Package.Name"></a>

<a id="Package.ImportPath"></a>

<a id="Package.Rel"></a>

<a id="Package.URL"></a>

<a id="Package.Synopsis"></a>

<a id="Package.IsCommand"></a>

<a id="Package.Doc"></a>

<a id="Package.DocMD"></a>

<a id="Package.Consts"></a>

<a id="Package.Vars"></a>

<a id="Package.Funcs"></a>

<a id="Package.Types"></a>

<a id="Package.Examples"></a>

<a id="Package.Files"></a>

### Package

```go
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.

<a id="Package.MarkdownURL"></a>

#### Package.MarkdownURL

```go
func (p *Package) MarkdownURL() string
```

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

<a id="Program"></a>

<a id="Program.Title"></a>

<a id="Program.Name"></a>

<a id="Program.Summary"></a>

<a id="Program.Body"></a>

<a id="Program.Markdown"></a>

<a id="Program.Headings"></a>

<a id="Program.Files"></a>

<a id="Program.Shot"></a>

<a id="Program.Missing"></a>

### Program

```go
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.

<a id="Program.MarkdownURL"></a>

#### Program.MarkdownURL

```go
func (p *Program) MarkdownURL() string
```

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

<a id="Program.SourceURL"></a>

#### Program.SourceURL

```go
func (p *Program) SourceURL() string
```

SourceURL is the example's directory on GitHub.

<a id="Program.URL"></a>

#### Program.URL

```go
func (p *Program) URL() string
```

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

<a id="Site"></a>

<a id="Site.Guides"></a>

<a id="Site.GuideGroups"></a>

<a id="Site.Programs"></a>

<a id="Site.Packages"></a>

<a id="Site.Groups"></a>

<a id="Site.Base"></a>

### Site

```go
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.

<a id="Type"></a>

<a id="Type.Name"></a>

<a id="Type.Doc"></a>

<a id="Type.DocMD"></a>

<a id="Type.Decl"></a>

<a id="Type.DeclText"></a>

<a id="Type.Src"></a>

<a id="Type.Consts"></a>

<a id="Type.Vars"></a>

<a id="Type.Funcs"></a>

<a id="Type.Methods"></a>

<a id="Type.Examples"></a>

<a id="Type.Members"></a>

### Type

```go
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.

<a id="Value"></a>

<a id="Value.Names"></a>

<a id="Value.Doc"></a>

<a id="Value.DocMD"></a>

<a id="Value.Decl"></a>

<a id="Value.DeclText"></a>

<a id="Value.Src"></a>

### Value

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

Value is a const or var block.