1. API

The API reference is generated from the solution declared by the control document’s :solution: attribute. It covers every namespace, type and member of the projects that solution contains, the solution decides which projects, and each .csproj decides which files. Neither is inferred from the directory tree.

When osisa-statiq renders the documentation site, this content is replaced by that generated reference. In every other renderer, GitHub, a plain AsciiDoc viewer, asciidoctor-pdf, the paragraph above is what a reader sees, which is why it is written to stand on its own.

1.1. Why this file exists

cmd/XXXX is a command macro: a target that names a command rather than a document. Written in a control document as

== API

include::cmd/API.adoc[leveloffset=+1]

it tells osisa-statiq to run the command API and substitute its output for this content. The chapter’s own title supplies the heading and its position in the navigation, so the document decides where the generated reference lands rather than the generator deciding for it.

The macro is carried by include:: deliberately. Both alternatives break outside this tool: link:cmd/API[] renders as a dead link labelled cmd/API, and inline links are modelled by the parser only inside table cells, so it is unreachable anyway, while cmd::API[] prints its own raw text into the chapter. An include:: degrades to real content, because there is real content here.

1.2. The rules

  • Resolved during staging, before the document reaches the renderer. Nothing bearing a cmd/ target survives into the rendered site.

  • An unknown command is a hard failure, naming it and listing the ones that exist. A command macro that is silently ignored renders an empty chapter and reports success.

  • API and BuildInfo are the defined commands. osisa-statiq --list-providers prints the list, in the form a control document writes.

1.3. Adding a command

A new one needs a name, a resolver that produces its content, registration so the unknown-command failure knows about it, a page like this one under cmd/ so the macro still renders for everyone else, and a test that drives it through the Sphinx provider.

The generator is osisa-statiq, a dotnet tool published from the NETCore repository; this repository consumes it by version through .config/dotnet-tools.json rather than carrying a copy of its source.