Skip to main content

internal/docsite/docsite.go

internal/docsite · 390 lines · 17 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 published document the navigation does not reach.

source

const keptMarker​

const keptMarker = "<!-- kept in the repository, not on the site"

keptMarker opens the comment in docs/SUMMARY.md naming the documents that stay in the repository: records for the people building Taisce, such as the decision register and dated measurement runs, rather than documentation for the people using it. The list is a comment so that GitHub, where the same file reads as a table of contents, shows nothing for it.

A list rather than a directory: the register's path is the one the project's rules and code comments cite, and moving files to change what a website shows would break every one of those.

source

var keptEntry​

var keptEntry = regexp.MustCompile(`^-\s+(\S+\.md)$`)

source

func publishedDocuments​

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

publishedDocuments removes the kept documents from docs. A document is on the site or kept, never both and never neither; checkListed refuses neither, and this refuses both, together with a kept name that is no document, because a list naming nothing is how a moved record goes unnoticed. It reads the navigation as written, before links are resolved, since a link to a kept document is rewritten to its source and would no longer read as listed.

source

func keptDocuments​

func keptDocuments(summary string) (map[string]bool, error)

keptDocuments reads the kept comment: one "- name.md" line per document, up to the comment's close.

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