sitegen

README

sitegen

A documentation site from a Go module's own source: the package comments, the exported API with its signatures, the tested examples with their output, a guide of markdown pages. Write ordinary documented Go and the site is the by-product.

go run github.com/Deufel/sitegen/cmd/sitegen -root . -out docs -title migrate -repo https://github.com/Deufel/migrate
go run github.com/Deufel/sitegen/cmd/sitegen -root . -check   # what the discipline lacks

The discipline is the standard one: an exported name carries a comment that begins with the name, a package carries a comment, a function carries an example with output. Check reports the gaps; a test refuses a release that forgets. Pages wear system.css from a CDN tag and nothing else.

Documentation

Overview

Package sitegen builds a documentation site from a Go module's own source: the package comments, the exported API, the tested examples, and a guide of markdown pages. The site is the by-product of writing ordinary, documented Go; nothing is written twice.

What the site is made of

Four sources, each optional except the source itself:

• README.md at the module root is the front page.
• Every package's doc comment (doc.go by convention) is its overview.
• Every exported identifier's doc comment is its reference entry, rendered with the signature printed from the syntax tree.
• Every Example function in a _test.go file is shown with its code and its Output block — go test proves the output, so the example cannot rot.
• Markdown files under guide/ (or the directory named in Config) are the narrative pages, ordered by their front matter.

The discipline it asks for

The standard one, the one pkg.go.dev already expects: an exported name carries a comment that begins with the name; a package carries a comment; anything worth showing carries an example with output. Check reports what is missing so a test can refuse a release that forgets.

The theme

Pages wear system.css from a CDN tag and nothing else; the generator ships no stylesheet and no script of its own. The shell is the engine's page grid: a header, a rail of sections, the page, an "On this page" aside, previous and next.

Index

• Constants
• func DocHTML(text string) string
• func Markdown(src string) string
• func Must(problems []Problem, err error) error
• type Config
• type Example
• type Package
  • func Packages(root string) ([]Package, error)
• type Page
• type Problem
  • func Check(root string) ([]Problem, error)
  • func CheckLinks(out string) ([]Problem, error)
  • func (p Problem) String() string
• type Site
  • func Build(cfg Config) (Site, error)
• type Symbol
• type Type

Constants

const (
	DefaultTheme       = "https://cdn.jsdelivr.net/gh/Deufel/system-css@v0.6.0/static/system.css"
	DefaultHighlight   = "https://cdn.jsdelivr.net/gh/Deufel/system-css@v0.6.0/static/highlight.css"
	DefaultHighlightJS = "https://cdn.jsdelivr.net/gh/Deufel/system-css@v0.6.0/static/highlight.js"
)

DefaultTheme — the engine at a tag; a site pins one and moves on purpose.

Functions

func DocHTML

func DocHTML(text string) string

DocHTML renders a Go doc comment (the go/doc/comment syntax: headings, lists, code blocks, links) to HTML.

func Markdown

func Markdown(src string) string

Markdown renders GitHub-flavoured markdown to HTML with heading ids.

func Must

func Must(problems []Problem, err error) error

Must fails when problems remain — the one-line guard for a test.

Types

type Config

type Config struct {
	Root    string // the module's directory (holds go.mod)
	Out     string // the site's directory (created; index.html and the pages)
	Title   string // the site's name; the module's last path element when empty
	Tagline string // a few words under the title
	Repo    string // the repository URL, linked from the header
	Guide   string // the markdown pages' directory relative to Root; "guide" when empty; absent is fine
	// Theme is the engine stylesheet's URL; the pinned system.css tag when
	// empty. Highlight is its syntax companion ("" = the tag's).
	Theme, Highlight, HighlightJS string
}

Config names the module and where its site goes.

type Example

type Example struct {
	Name   string // the example's full name (ExampleRun_backup)
	For    string // the symbol it documents ("" = the package)
	Suffix string // the part after the underscore
	Doc    string
	Code   string
	Output string
}

Example is one Example function: what it shows, its code, its output.

type Package

type Package struct {
	ImportPath string
	Name       string
	Dir        string   // relative to the module root
	Doc        string   // the package comment, raw
	Synopsis   string   // its first sentence
	Consts     []Symbol // exported, grouped as declared
	Vars       []Symbol
	Types      []Type
	Funcs      []Symbol // package-level functions
	Examples   []Example
}

Package is one Go package as the site reads it.

func Packages

func Packages(root string) ([]Package, error)

Packages reads every package under root (the module's directory): directories holding non-test Go files, except testdata, vendor, hidden and internal ones. The import path is the module path joined with the directory.

type Page

type Page struct {
	Path    string // relative to Out ("index.html", "guide/start.html", "pkg/migrate.html")
	Title   string
	Section string // "" (home) · "guide" · "pkg"
	Order   int
	Body    string // the rendered HTML inside the measure
}

Page is one rendered page of the site.

type Problem

type Problem struct {
	Package string
	Kind    string // "package-doc" · "symbol-doc" · "example" · "link"
	Name    string
}

Problem is one thing the module's documentation lacks.

func Check

func Check(root string) ([]Problem, error)

Check reads the module and reports what the discipline asks for and the source lacks: a package without a comment, an exported symbol without one, a package-level function with no example. A test asserts the list is empty; the strictness is the caller's — filter by Kind for the level a project keeps.

func CheckLinks

func CheckLinks(out string) ([]Problem, error)

CheckLinks walks the built site and reports every relative link that names a file the site lacks.

func (Problem) String

func (p Problem) String() string

type Site

type Site struct {
	Pages    []Page
	Packages []Package
}

Site is what Build wrote.

func Build

func Build(cfg Config) (Site, error)

Build reads the module and writes the site. It answers the pages it wrote, so a test can look at them without reading the disk again.

type Symbol

type Symbol struct {
	Name string
	Sig  string // the declaration as printed, bodies stripped
	Doc  string
}

Symbol is one exported declaration: its printed signature and its comment.

type Type

type Type struct {
	Symbol
	Funcs   []Symbol // constructors: functions returning the type
	Methods []Symbol
}

Type is an exported type with the functions and methods that belong to it.