Skip to main content

Documenting a Component

This tutorial shows how to set up documentation for an Ideal component, including API reference from Doxygen and content pages organized with docs.xml.

Prerequisites​

Create docs.xml​

The documentation module is loaded automatically by find_package(IdealCmakeModules REQUIRED) — no changes to CMakeLists.txt are needed. Documentation generation is controlled entirely at configure time through the BUILD_DOCS option and the docs.xml file.

Create a docs.xml file in the project root. Start with a minimal API reference:

<?xml version="1.0" encoding="UTF-8" ?>
<docs>
  <developer>
    <reference>
      <api title="greeting" />
    </reference>
  </developer>
</docs>

This scans headers in include/ by default. To scan additional directories, add <input> elements:

<api title="greeting">
  <input path="include" />
  <input path="src/internal" />
</api>

Document Your Headers​

Add Doxygen comments to your public API:

/**
 * @defgroup greeting Greeting
 * @brief Functions for generating greeting messages.
 * @{
 */

/**
 * Returns a greeting message for the given name.
 *
 * The returned string points to a static buffer and is overwritten
 * on each call.
 *
 * @param name  The name to greet.
 * @return A greeting string.
 */
const char *greeting_hello(const char *name);

/** @} */

Build the Documentation​

make docs

The generated documentation appears under build/docs/.

Organize the API​

Use <group> and <page> elements to control the navigation hierarchy. Groups correspond to @defgroup in source code, pages to @page:

<api title="greeting">
  <group refid="greeting" />
  <group refid="farewell" />
  <page refid="error-codes" />
</api>

Groups and pages can be nested to create deeper hierarchies:

<api title="greeting">
  <group refid="public-api">
    <group refid="greeting" />
    <group refid="farewell" />
  </group>
  <page refid="error-codes" />
</api>

Add Content Pages​

Beyond the API reference, you can add Markdown documents for guides and explanations. Create a how-to guide:

docs/developer/howto/custom-greeting.md:

# Custom Greeting Format

Override the default greeting format by providing a format string
to `greeting_hello_fmt()`.

## Steps

1. Include the header:
   ...

Reference it from docs.xml:

<docs>
  <developer>
    <reference>
      <api title="greeting">
        <group refid="greeting" />
      </api>
    </reference>
    <howto>
      <document path="docs/developer/howto/custom-greeting.md" />
    </howto>
  </developer>
</docs>

Documents are ordered by their position in docs.xml. Each Markdown file must start with a # Title line — frontmatter is injected automatically. See Documentation — docs.xml configuration for the full schema reference.

Summary​

Your component now has:

  • API reference generated from Doxygen comments in source code
  • Groups and pages to organize the API navigation
  • Content pages for guides and other documentation