doc

Arguments and rejection

topaz doc accepts no positional source operand. --root <dir> selects a package containing topaz.toml and defaults to the current directory.

--out-dir <dir> is required and must name a nonempty directory path. --compiler selects self or rust, with self as the default. --verbose reports that selection on standard error.

Applicable language and compiler resource options use the common compiler validation rules. --locked requests package lock verification. Source operands, output-format options, program arguments, missing values, repeated options, and attached values are rejected before documentation generation.

Output

Successful generation leaves standard output empty and reports the output directory on standard error. Parse, resolver, checker, lock, and I/O diagnostics use standard error.

exports.json contains the checked public export surface defined by check --exports-json. index.md contains the package documentation derived from those exports and their source documentation comments.

--format json is rejected because doc has no JSON console report mode. The exports.json artifact is still produced on success because it has a distinct purpose from command presentation.

Exit status

Exit code 0 means both documentation files were generated and written.

Exit code 1 covers invalid arguments, invalid or unreadable packages, failed lock verification, parsing, resolution or checking errors, invalid compiler export products, compiler resource failures, and directory or output write failures.

Filesystem effects

The command reads the package, imported sources, dependency content, and documentation comments. It creates the requested output directory if needed.

After successful checking, it writes exports.json and then index.md. Existing files at those two paths may be replaced. Other files are preserved.

A failure before output writing leaves both output files unchanged. A later I/O failure can leave one updated file or a partial file. The command returns failure and does not report completed documentation.

Network access

Documentation generation makes no network requests and does not execute the package, fetch dependencies, or launch a documentation server.

Reproducibility

The same compiler and language mode, source and comment bytes, package configuration, and locked dependency identities produce identical documentation bytes. Export ordering is deterministic and output content does not include a generation timestamp.

The completion message includes the selected destination. Path-sensitive diagnostics require identical path inputs for identical text.

Packages and locks

Documentation is always a package operation. --locked verifies the current lock before checking and never updates it. Registry dependencies and Lispex configuration require the applicable locked package checks.

The command leaves the manifest, lock, dependency source, and vendor tree unchanged. The requested output directory does not become the package root.

The invocation topaz doc main.tpz --language-version 5.21 is expected to exit with 1.