docs#

Configure (if needed) and build or check project documentation.

clibra docs build --preset docs                 # build all doc targets
clibra docs build --target api --preset docs    # Doxygen API docs only
clibra docs build --target sphinx --preset docs # Sphinx docs only
clibra docs check --kind doxygen --preset docs  # check Doxygen markup

Requires LIBRA_DOCS to be ON in the preset’s CMake cache.

Subcommands#

build

Build documentation. With no --target, builds both apidoc and sphinxdoc independently, so a project with only Doxygen or only Sphinx works without special configuration. --target api builds just the Doxygen API docs; --target sphinx builds just the Sphinx docs.

check

Check documentation consistency. --kind is required and selects the check: clang runs the clang-based API-doc check, doxygen runs the Doxygen markup check.

If a target is listed as unavailable by the build system, clibra reports an error with the reason rather than a generic failure.

CMake equivalent#

# build
cmake --build --preset <name> --target apidoc     # --target api
cmake --build --preset <name> --target sphinxdoc  # --target sphinx

# check
cmake --build --preset <name> --target apidoc-check-clang    # --kind clang
cmake --build --preset <name> --target apidoc-check-doxygen  # --kind doxygen

For documentation tool configuration, see Documentation.

Flag reference#

clibra docs#

Configure (if needed) and build/check documentation.

Requires LIBRA_DOCS=ON in the preset’s CMake cache. The preset defaults to docs if not given.

Attempts to build both apidoc and sphinxdoc targets independently. If a target is listed as unavailable by the build system, it is skipped with a warning rather than an error. Has suboptions for checking documentation.

Usage: clibra docs [OPTIONS] <COMMAND>

Subcommands:#

  • clibra docs build — Build API/sphinx documentation targets

  • clibra docs check — Check API docs for consistency/content validity

Options:#

  • -D <VAR=VALUE>

  • -k, --keep-going — Continue building after errors. Only valid with {Ninja, Unix Makefiles} generators

  • -r, --reconfigure — Force the configure step even if the build directory exists

  • -f, --fresh — Reconfigure with a –fresh cmake build directory

clibra docs build#

Build API/sphinx documentation targets

Usage: clibra docs build [OPTIONS]

Options:#

  • -t, --target <TARGET>

    Possible values: sphinx, api

  • -k, --keep-going — Continue building after errors. Only valid with {Ninja, Unix Makefiles} generators

  • -r, --reconfigure — Force the configure step even if the build directory exists

  • -f, --fresh — Reconfigure with a –fresh cmake build directory

clibra docs check#

Check API docs for consistency/content validity

Usage: clibra docs check [OPTIONS] --kind <KIND>

Options:#

  • --kind <KIND> — Check doxygen markup

    Possible values: clang, doxygen

  • -k, --keep-going — Continue building after errors. Only valid with {Ninja, Unix Makefiles} generators

  • -r, --reconfigure — Force the configure step even if the build directory exists

  • -f, --fresh — Reconfigure with a –fresh cmake build directory