A documentation target is still a target
It is added, generated and regenerated exactly as a language target is, on the same merge-or-overwrite rules. The only difference is where it points.
Generates documentation targets. An sdkgen package rather than a separate tool. sdkgen defines a `docs` kind, a target whose destination is a documentation system rather than a language; docgen supplies the items for it. Checked against the source repository, which is the authority where it and this page disagree.
What it is#
What docgen demonstrates matters as much as what it does. sdkgen's verbs are built from a kind registry, so a package that supplies a new kind gets its own add command with no dispatch code written for it. docs is such a kind, and docgen supplies the items.
That is the extension model for the whole toolchain. A new capability ships as a package that an existing project installs, rather than as a change to the generator that every project inherits. Dart, Haskell and Lean arrive the same way, together in @voxgig/sdkgen-langpack, and the Seneca provider in @voxgig/sdkgen-infrapack.
docgen is published, and its own repository is the authority on what it emits.
docgen 0.29.2 emits three editions. summary writes a few pages of Markdown orientation to SUMMARY.md: capabilities, connection, first request, SDKs and tools. github-pages writes a static HTML site to docs/: the API, SDK, feature and tool reference, guides, local search and authored pages. It also writes a workflow and a setup script for publishing the site on GitHub Pages. presentation writes editable Slidev Markdown for a slide deck. A new project from create-sdkgen installs the first two by default.
Concepts#
The ideas you need to hold to use it, and the ones that cost time when nobody told you.
Packages are how the toolchain grows
voxgig-sdkgen package add <pkg> installs everything a package provides. --only <kind>:<name> narrows that to a subset, and --alias <name>=<alias> installs under a different name, which is what lets two packages supplying the same target name coexist.
Examples#
Commands and API calls are as the component's own documentation gives them. Every example marked with a source is copied from that public repository, so it can be checked rather than trusted.
Install a documentation target
The package is a development dependency of the SDK project, and package add registers what it supplies into .sdk/. From then on it regenerates with everything else.
npm install --save-dev @voxgig/docgen
cd <sdk-project>/.sdk
voxgig-sdkgen package add @voxgig/docgen
npm run build && npm run generateReference#
The lookup tables. The first-party documentation below goes deeper on every row.
Package commands
| Name | What it is |
|---|---|
package add <pkg> | Install everything the package provides. |
package add <pkg> --only docs:<name> | Install one item rather than all of them. |
package update <pkg> | Refresh an installed package. |
package check <path> | Validate a package. Runs where there is no project. |
First-party documentation#
The first-party documentation goes all the way down, and it is the authority.
The rest of the toolchain#
- sdkgen Turns the model into SDKs.
- apidef Turns a spec into a model.
- create-sdkgen Scaffolds a project.
- apigen Not yet published.
Read the generated code#
The toolchain is MIT and open, and the catalog holds 600+ generated SDKs readable without installing anything.