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#
docgen is worth understanding for what it demonstrates as much as for 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. Haskell arrived the same way, as @voxgig/sdkgen-haskell.
This page is shorter than the two before it, deliberately. docgen is real and published, and its own repository is the authority on what it currently emits.
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 dev 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#
This page summarises at the altitude a decision needs. These go all the way down, and they are 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.