Library usage

uid: guides.library description: Build documentation from Pudu code with Docset.build and Build.plan, and extend it with page transforms and output post-processors.

Everything the command line does is available to Pudu programs. Call the package directly to build sites from a larger tool, add pages or files during a build, or check a project in tests.

Entry points

Build a project

export fn build(configFile: Str, chosen: &Options, extending: &Build.Extensions) -> Result[Docgen.Report, Array[Docgen.Diagnostic]]

<xref:PuduLangDocgen.Docset.build> reads the configuration, loads every file the project uses, builds the site, and publishes it. On success it returns a <xref:PuduLangDocgen.Report> listing the files written, unchanged, and removed, with any warnings. On failure it returns every diagnostic, and nothing is written.

<xref:PuduLangDocgen.Docset.Options> layers command-line choices over the configuration. Start from <xref:PuduLangDocgen.Docset.options>, which changes nothing, and set the fields you need:

!code-pudu[]

Extend a build

<xref:PuduLangDocgen.Build.Extensions> holds two lists of functions that run during a build:

export type Extensions = { pages: Array[fn(Docgen.Page) -> Docgen.Page], artifacts: Array[fn(Array[Docgen.Artifact]) -> Array[Docgen.Artifact]] }

Use <xref:PuduLangDocgen.Build.extensions> when you need none.

Page transforms

A page transform returns the page it is given, changed or not. The kind of a page is article, rest, api-page, catalog, landing, redirect, or not-found for content, and api-module, api-type, or api-member for generated Pudu reference pages. A transform can use it to target one family of pages; the layout also exposes it as a kind-<kind> class on the page body.

!code-pudu[]

Changes made by a page transform are validated with the rest of the site: a fragment link to a heading the transform removed is still reported.

Post-processors

A post-processor receives every output file and returns the files to publish. It can add, remove, or rewrite files; the result is checked for portable, unique paths before anything is written.

!code-pudu[]

Build without writing

<xref:PuduLangDocgen.Build.plan> is a pure function: given loaded input, it returns the complete <xref:PuduLangDocgen.Plan> of files and resources, or every error. Tests can use it to check a documentation project without an output folder:

match Docset.load("docs/docgen.json", &Docset.options()) {
  case Ok(loaded) => match Build.plan(&loaded.input, &Build.extensions()) {
    case Ok(plan) => plan.diagnostics.isEmpty()
    case Err(_problems) => false
  }
  case Err(_problems) => false
}

Diagnostics

Every failure is a <xref:PuduLangDocgen.Diagnostic> with a stable code, a <xref:PuduLangDocgen.Severity>, the file, the line, and a message. <xref:PuduLangDocgen.failed> tells whether a list holds an error. The codes are listed in the diagnostics reference.