Commands · reference
config-weave docs
docs renders a static wdoc site from the playbook's own metadata: the descriptions on plays, steps, variables, packages, resources, composites and gatherers. It walks the validated model, writes a wdoc source file named _weave_docs.wcl into the output directory, and shells out to the wcl CLI to build the HTML next to it. config-weave does not embed a renderer, so wcl must be installed. A playbook that does not validate does not document.
Synopsis
config-weave docs [OPTIONS] <PLAYBOOK_DIR> [OUTDIR]
Arguments
| Argument | Meaning |
|---|---|
| PLAYBOOK_DIR | The playbook directory. |
| OUTDIR | Where to write the site. Optional. Defaults to docs/ inside the playbook directory. Created when missing. |
Options
The global options are accepted, and none changes what is documented: docs reads the playbook's declarations, not the values a run would bind.
| Option | Value | Meaning |
|---|---|---|
| --serve | After rendering, hand the output directory to wcl wdoc serve, a development server that rebuilds on demand from its console. The command does not return until the server stops. | |
| --addr | ADDR | Listen address for --serve. Default 127.0.0.1:8080. Requires --serve. |
| --pkg-only | Document only the packages. The playbook's plays, variables and gathered facts are skipped. Use it for a package repository whose playbook exists only as a validation harness. |
Set CONFIG_WEAVE_WCL to the path of a specific wcl binary when the one on PATH is not the one you want.
Examples
Render the site into the default location.
config-weave docs ./my-playbook
rendered 7 page(s) to ./my-playbook/docs
Render a package repository's docs into a build directory and preview them.
config-weave docs ./config-weave-pkgs ./site --pkg-only --serve --addr 0.0.0.0:9000
Exit status
0 when the site rendered, and when --serve was given, once the server has stopped. 2 when the playbook did not validate, the output directory could not be created, or the wcl CLI could not be run.