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.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | lakeRoot | RepoPath | yes | The 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. |
| in | lib | InstanceId | yes | The 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 |
| in | platform | RepoPath | The 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. | |
| in | restore | Flag | Restore 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 | |
| in | allowCold | Flag | Build 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 | |
| in | dryRun | Flag | Run every guard, print the build command, build nothing. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| out | render | RepoPath | <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:
| process | step | lane | via skill |
|---|---|---|---|
| Publish a folio’s Lean render with the harness chrome | Build the doc-gen4 render over the warm cache | Lean toolchain | lean-html-docs |
| Publish a folio’s Lean render with the harness chrome | Stage the render under the site and rail every page | CI/CD Pipeline | lean-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.
| install | none |
| runtime | bash, git, lake |
| network | yes |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
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. |
| when to choose it | |
|---|---|
| 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. |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-sci/tools/lean-html-docs/lean-html-docs.ts | |
| script | folio-assistant-sci/adapters/paper/lean/lean-docs-build.sh |
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."
}
}