Build a Lean package’s HTML docs (doc-gen4)

Build the doc-gen4 HTML render of a folio’s Lake package — the visualiser of a declared lean directory — with lake -R -Kenv=dev build <Lib>:docs, cache-aware: refuses while another lake/lean process holds .lake/, refuses on a restored tree that carries no traces (a Lake build there EVICTS the cache), checks or restores the warm cache first, and enables a sentinel-commented doc-gen4 [[require]] for this build only, restoring the lakefile on exit. Never runs lake update. Output: <lake-root>/.lake/build/doc.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

lean-html-docs

Build and publish the visualiser of a folio’s declared lean directory: the package’s doc-gen4 HTML render, staged under the folio’s site and wrapped in the harness navbar and rail. Use when a folio’s Lean docs are missing, stale, or published without the harness chrome, or when declaring a lean directory and its coverage.visualiser.

Source: folio-assistant-sci/skills/lean/lean-html-docs.md.

Also satisfied by: lean-kg-publish, lean-render-publish.

The skill declares no I/O contract (schemas/skills/lean-html-docs/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inlakeRootRepoPathyesThe Lake package directory whose lakefile requires (or sentinel-comments) doc-gen4, e.g. folio/quantum-observable-universe/lean.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inlibInstanceIdyesThe lean_lib to document, e.g. QOU (a Lean library name: alphanumerics, dot, underscore, hyphen). Repeat for several.string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$ · A workflow instance id — the stem of a file in the bean graph’s workflow-state node
inplatformRepoPathThe index checkout holding lake-cache.sh. Default $FOLIO_ASSISTANT_ROOT.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inrestoreFlagRestore the warm cache first (about 2 minutes) instead of only checking it.boolean · A boolean switch — projects to a bare flag, with no value word
inallowColdFlagBuild without a warm cache: Mathlib from source, 30-60 minutes before doc-gen4 starts.boolean · A boolean switch — projects to a bare flag, with no value word
indryRunFlagRun every guard, print the build command, build nothing.boolean · A boolean switch — projects to a bare flag, with no value word
outrenderRepoPath<lake-root>/.lake/build/doc, doc-gen4’s output, printed as the last line. Feed it to lean-render-publish.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.

Processes and tasks

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
Publish a folio’s Lean render with the harness chromeBuild the doc-gen4 render over the warm cacheLean toolchainlean-html-docs
Publish a folio’s Lean render with the harness chromeStage the render under the site and rail every pageCI/CD Pipelinelean-html-docs

How it is deployed and reached

  • Command line. From the repository root: bash folio-assistant-sci/adapters/paper/lean/lean-docs-build.sh.
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebash, git, lake
networkyes

When a host it reaches is refused:

host / errorremedy
github.comnone: doc-gen4 and its dependencies are fetched from GitHub on first use, and the warm cache is stored there; without it there is no render.
when to choose it
whenA folio’s declared lean directory needs its visualiser (the doc-gen4 render) built or refreshed, before lean-render-publish wraps it.
limitsdoc-gen4 renders the WHOLE import closure, Mathlib included. It does not prune; prune at publish. Refuses, rather than risks, a shared or untraced .lake/. Never run it while another agent holds the folio’s Lean cache.
costUnmeasured. One doc-gen4 compile, then one doc pass per module of the closure — thousands for a Mathlib package; qou’s July render was 4,193 pages, 545 MB. Needs that much free disk beyond the build.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-sci/tools/lean-html-docs.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/folio-assistant-sci/folio-assistant-sci.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/folio-assistant-sci/tools/lean-html-docs.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-sci/folio-assistant-sci.jsonld",
  "name": "lean-html-docs",
  "title": "Build a Lean package's HTML docs (doc-gen4)",
  "description": "Build the doc-gen4 HTML render of a folio's Lake package — the visualiser of a declared `lean` directory — with `lake -R -Kenv=dev build <Lib>:docs`, cache-aware: refuses while another lake/lean process holds `.lake/`, refuses on a restored tree that carries no traces (a Lake build there EVICTS the cache), checks or restores the warm cache first, and enables a sentinel-commented doc-gen4 `[[require]]` for this build only, restoring the lakefile on exit. Never runs `lake update`. Output: `<lake-root>/.lake/build/doc`.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bash folio-assistant-sci/adapters/paper/lean/lean-docs-build.sh"
  },
  "io": {
    "inputs": [
      {
        "name": "lakeRoot",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The Lake package directory whose lakefile requires (or sentinel-comments) doc-gen4, e.g. `folio/quantum-observable-universe/lean`.",
        "required": true,
        "arg": {
          "flag": "--lake-root"
        }
      },
      {
        "name": "lib",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/InstanceId",
        "description": "The `lean_lib` to document, e.g. `QOU` (a Lean library name: alphanumerics, dot, underscore, hyphen). Repeat for several.",
        "required": true,
        "arg": {
          "flag": "--lib"
        }
      },
      {
        "name": "platform",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The index checkout holding `lake-cache.sh`. Default `$FOLIO_ASSISTANT_ROOT`.",
        "required": false,
        "arg": {
          "flag": "--platform"
        }
      },
      {
        "name": "restore",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Restore the warm cache first (about 2 minutes) instead of only checking it.",
        "required": false,
        "arg": {
          "flag": "--restore"
        }
      },
      {
        "name": "allowCold",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Build without a warm cache: Mathlib from source, 30-60 minutes before doc-gen4 starts.",
        "required": false,
        "arg": {
          "flag": "--allow-cold"
        }
      },
      {
        "name": "dryRun",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Run every guard, print the build command, build nothing.",
        "required": false,
        "arg": {
          "flag": "--dry-run"
        }
      }
    ],
    "outputs": [
      {
        "name": "render",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "`<lake-root>/.lake/build/doc`, doc-gen4's output, printed as the last line. Feed it to `lean-render-publish`."
      }
    ]
  },
  "satisfies": [
    "lean-html-docs"
  ],
  "requirements": {
    "runtime": [
      "bash",
      "git",
      "lake"
    ],
    "network": true
  },
  "remedies": [
    {
      "host": "github.com",
      "none": "doc-gen4 and its dependencies are fetched from GitHub on first use, and the warm cache is stored there; without it there is no render."
    }
  ],
  "selection": {
    "when": "A folio's declared `lean` directory needs its visualiser (the doc-gen4 render) built or refreshed, before `lean-render-publish` wraps it.",
    "limits": "doc-gen4 renders the WHOLE import closure, Mathlib included. It does not prune; prune at publish. Refuses, rather than risks, a shared or untraced `.lake/`. Never run it while another agent holds the folio's Lean cache.",
    "cost": "Unmeasured. One doc-gen4 compile, then one doc pass per module of the closure — thousands for a Mathlib package; qou's July render was 4,193 pages, 545 MB. Needs that much free disk beyond the build."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev