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 Entry
• 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

Examples

• Build
• Check
• CheckLinks
• DocHTML
• Markdown
• Must
• Packages

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"
	DefaultDatastar    = "https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.4/bundles/datastar.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.

Example

package main

import (
	"fmt"

	"github.com/Deufel/sitegen"
)

func main() {
	fmt.Println(sitegen.DocHTML("Add answers a plus b.\n\n# Why\n\nBecause."))
}

Output:
<p>Add answers a plus b.
<h3 id="hdr-Why">Why</h3>
<p>Because.

func Markdown

func Markdown(src string) string

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

Example

package main

import (
	"fmt"

	"github.com/Deufel/sitegen"
)

func main() {
	fmt.Print(sitegen.Markdown("## Start\n\nA *word*.\n"))
}

Output:
<h2 id="start">Start</h2>
<p>A <em>word</em>.</p>

func Must

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

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

Example

package main

import (
	"fmt"
	"strings"

	"github.com/Deufel/sitegen"
)

func main() {
	err := sitegen.Must([]sitegen.Problem{{Package: "p", Kind: "example", Name: "Run"}}, nil)
	fmt.Println(strings.Split(err.Error(), "\n")[0])
}

Output:
sitegen: 1 problems

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; with Ref, every symbol links to its source line
	Ref     string // the branch, tag or commit the source links point at; "HEAD" when empty
	Guide   string // the markdown pages' directory relative to Root; "guide" when empty; absent is fine
	Front   string // the front page's markdown file relative to Root; "README.md" when empty
	// Theme is the engine stylesheet's URL; the pinned system.css tag when
	// empty. Highlight is its syntax companion ("" = the tag's). Datastar
	// drives the search dialog ("" = the free bundle at a tag).
	Theme, Highlight, HighlightJS, Datastar string
}

Config names the module and where its site goes.

type Entry

type Entry struct {
	Title  string
	Kind   string // "page" · "const" · "var" · "func" · "type" · "method" · "example" · "heading"
	Anchor string // "" = the page itself
	Page   string // the page's path (filled by Build)
	Where  string // the page's title, shown beside a hit
}

Entry is one thing the site-wide search can land on: a page, a symbol, an example, a heading.

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
	File   string
	Line   int
}

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

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.

Example

package main

import (
	"fmt"

	"github.com/Deufel/sitegen"
)

func main() {
	pkgs, _ := sitegen.Packages("testdata/mod")
	for _, p := range pkgs {
		fmt.Println(p.ImportPath, "—", p.Synopsis, "—", len(p.Funcs), "functions,", len(p.Examples), "examples")
	}
}

Output:
example.com/thing/thing — Package thing adds numbers. — 2 functions, 2 examples

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
	Index   string  // the page's own index for the n3 rail: a package's symbols by kind, a markdown page's headings
	Entries []Entry // what the search finds on this page
}

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.

Example

package main

import (
	"fmt"

	"github.com/Deufel/sitegen"
)

func main() {
	problems, _ := sitegen.Check("testdata/mod")
	for _, p := range problems {
		fmt.Println(p)
	}
}

Output:
example.com/thing/thing: symbol-doc Undocumented
example.com/thing/thing: example Undocumented

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.

Example

package main

import (
	"fmt"
	"os"

	"github.com/Deufel/sitegen"
)

func main() {
	out, _ := os.MkdirTemp("", "site")
	_, _ = sitegen.Build(sitegen.Config{Root: "testdata/mod", Out: out})
	problems, _ := sitegen.CheckLinks(out)
	fmt.Println(len(problems), "broken links")
}

Output:
0 broken links

func (Problem) String

func (p Problem) String() string

String reads "package: kind name".

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.

Example

package main

import (
	"fmt"
	"os"

	"github.com/Deufel/sitegen"
)

func main() {
	out, _ := os.MkdirTemp("", "site")
	site, _ := sitegen.Build(sitegen.Config{Root: "testdata/mod", Out: out, Title: "thing"})
	for _, p := range site.Pages {
		fmt.Println(p.Path, "—", p.Title)
	}
}

Output:
index.html — thing
guide/start.html — Getting started
pkg/thing.html — thing

type Symbol

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

Symbol is one exported declaration: its printed signature, its comment, and where it is written (the file relative to the module root, the line).

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.