Skip to content

documentation.md

Latest commit

 

History

History
84 lines (65 loc) · 2.9 KB

documentation.md

File metadata and controls

84 lines (65 loc) · 2.9 KB
Raw

Documentation Build Tools

LabKit uses three public MATLAB entry points for its documentation sources and generated site. renderLabKitDocs builds and synchronizes the site; checkLabKitDocs performs independent builds and verifies deterministic generated output; maintainLabKitDocLinks checks or repairs standard relative Markdown links. Path-organized Markdown and MATLAB help blocks are the authored sources.

Maintain Links

result = maintainLabKitDocLinks
result = maintainLabKitDocLinks(repoRoot)
result = maintainLabKitDocLinks(repoRoot, "Update", true)

The default is read-only. With Update=true, a missing Markdown target is rewritten only when filename and link label identify exactly one current page. Review the rewritten diff, then rerun the default check.

Render The Site

result = renderLabKitDocs
result = renderLabKitDocs(sourceRoot)
result = renderLabKitDocs(sourceRoot, outputRoot)
repoRoot = "/path/to/LabKit-MATLAB-Workbench";
addpath(fullfile(repoRoot, "tools", "docs"))
result = renderLabKitDocs( ...
    fullfile(repoRoot, "docs"), fullfile(repoRoot, "site"));

Empty or omitted roots default to docs/ and site/ beneath the current LabKit repository. The result contains pageCount, apiCount, fileCount, sourceRoot, and outputRoot.

The default site/ folder is ignored by Git. Generate it when local offline reading or presentation inspection is useful; GitHub Actions independently generates the deployed site from main.

Rendering discovers every Markdown page, public App, history record, and complete public help contract. It first creates a complete temporary tree, then creates outputRoot when absent, copies new or changed files, deletes obsolete generated files and empty directories, and preserves the output root itself. Every eligible Markdown page is included automatically, and no duplicated navigation catalog exists in this model.

Check The Tracked Site

result = checkLabKitDocs
result = checkLabKitDocs(sourceRoot)
result = checkLabKitDocs(sourceRoot, existingSiteRoot)

Without an existing site argument, the check renders to two independent temporary folders and compares generated file paths and bytes. Supplying an existing site compares one independent render with that folder. A difference raises LabKit:Docs:StaleGeneratedSite; the result otherwise includes comparedFileCount in addition to the renderer result fields.

Build Tasks

The supported command-line wrappers are:

buildtool docs
buildtool docsCheck

Use docs when sources changed and docsCheck when validation must prove the renderer is deterministic. Never track or edit files under site/ manually.

Related Documentation