Skip to main content

internal/docsite/docsite.go

internal/docsite · 316 lines · 13 declarations · source

This file carries the package documentation, rendered on the package page.

Declarations​

type Options​

type Options struct {
	// Root is the repository checkout.
	Root string
	// Out is the renderer's document directory. It is replaced on every build, so it must be a
	// directory of its own: never the repository, never an ancestor of it, never inside docs/.
	Out string
	// Sidebars is the file the navigation is written to, in the renderer's sidebar format.
	Sidebars string
	// DSN names a disposable PostgreSQL substrate. The build creates a scratch database there,
	// migrates and inspects it, and drops it. Bootstrapping resets the instance roles' passwords the
	// way the test suite does, so this must never be a deployment's database.
	DSN string
	// Repo and Ref are where source links point: "owner/name" and a commit or branch.
	Repo, Ref string
}

Options says where the repository is, where the site's source goes, and what source links point at.

source

type Report​

type Report struct {
	Documents, Packages, Files, Declarations, Tests, Migrations, Tables int
}

Report counts what the build covered, so a caller can say it rather than claim it.

source

type page​

type page struct {
	Repo, Stage string
	Body        string
}

page is one staged markdown file. Repo is its path in the repository ("" when generated), Stage is its path under the document directory.

source

const summaryMarker​

const summaryMarker = "<!-- generated reference -->"

summaryMarker is where the generated reference is spliced into docs/SUMMARY.md.

source

func Build​

func Build(ctx context.Context, opts Options) (Report, error)

Build writes the site's source and returns what it covered.

source

method Options.validate​

func (o Options) validate() error

source

func stageDocuments​

func stageDocuments(root string) ([]page, string, error)

stageDocuments reads every markdown file under docs/ and returns the navigation file separately. The repository README is not a page: it is the repository's front door on GitHub, and the site has its own.

source

func spliceSummary​

func spliceSummary(summary, nav string) (string, error)

source

func checkListed​

func checkListed(summary string, docs []page) error

checkListed refuses a written document the navigation does not reach.

source

var leadingComments, alertStart, admonition​

var (
	leadingComments = regexp.MustCompile(`^(?:\s*<!--[\s\S]*?-->\s*\n)+`)
	alertStart      = regexp.MustCompile(`^>\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*$`)
	admonition      = map[string]string{"NOTE": "note", "TIP": "tip", "IMPORTANT": "info", "WARNING": "warning", "CAUTION": "danger"}
)

source

func forRenderer​

func forRenderer(body string) string

forRenderer adapts a page written for GitHub to the renderer, without changing what it says: the licence comment belongs to the source file rather than the rendered page, and a GitHub alert becomes the renderer's admonition of the same kind.

source

func writeSite​

func writeSite(opts Options, pages []page, sidebars []byte) error

writeSite replaces the document directory with the pages and writes the navigation.

source

func relative​

func relative(fromStage, toStage string) string

relative returns the shortest link from one staged page to another staged path (which may carry an anchor).

source