Fix Sphinx/Doxygen documentation build warnings treated as errors

doc/Doxyfile

@@ -64,7 +64,7 @@ WARN_IF_UNDOCUMENTED   = NO
 WARN_IF_DOC_ERROR      = YES
 WARN_IF_INCOMPLETE_DOC = YES
 WARN_FORMAT            = "$file:$line: $text"
-WARN_LOGFILE           = ./build/doxygen/warnings.log
+WARN_LOGFILE           = ./doxy_files/warnings.log
 
 #---------------------------------------------------------------------------
 # Input

doc/source/conf.py

@@ -26,6 +26,9 @@
     'sphinx_design',
 ]
 
+# ── autosectionlabel configuration ───────────────────────────────────────
+autosectionlabel_prefix_document = True
+
 # ── Breathe configuration ────────────────────────────────────────────────
 breathe_projects         = {"docraft": os.path.join(_doc_root, "doxy_files", "xml")}
 breathe_default_project  = "docraft"

doc/source/examples/shipping_label.rst

@@ -92,6 +92,7 @@ Template — ``shipping_label.craft``
            </Layout>
        </Body>
    </Document>
+
 Data — ``shipping_label.json``
 -------------------------------
 

docraft/include/craft/parser/docraft_parser_helpers.h

@@ -10,17 +10,17 @@
 
 namespace docraft::craft::parser::detail {
     /**
-     * @brief Parses a color attribute value into a DocraftColor.
-     * Supports hex colors (#RRGGBB or #RRGGBBAA) and named colors.
-     * @param color_attr XML attribute containing the color value.
-     * @return Parsed DocraftColor.
+     * @brief Checks whether a string is a valid hex color.
+     * Supports hex colors (\#RRGGBB or \#RRGGBBAA).
+     * @param color String to check.
+     * @return True if the string is a valid hex color, false otherwise.
      */
     bool is_hex_color(const std::string &color);
 
     /**
-     * @brief Parses a color string into a DocraftColor object.
-     * Supports hex colors (e.g., #RRGGBB or #RRGGBBAA) and named colors (e.g., "red", "blue").
-     * @param color_str The color string to parse.
+     * @brief Parses a color attribute value into a DocraftColor object.
+     * Supports hex colors (e.g., \#RRGGBB or \#RRGGBBAA) and named colors (e.g., "red", "blue").
+     * @param color_attr XML attribute containing the color value.
      * @return A DocraftColor object representing the parsed color.
      * @throws std::invalid_argument if the color string is not in a valid format or is an unsupported named color.
      */

docraft/include/docraft_color.h

@@ -28,8 +28,8 @@ namespace docraft {
         float b=0.0F;
         float a=1.0F;
         /**
-         * @brief Converts the RGBA color to a hex string #RRGGBBAA.
-         * @return Hex string in #RRGGBBAA format.
+         * @brief Converts the RGBA color to a hex string \#RRGGBBAA.
+         * @return Hex string in \#RRGGBBAA format.
          */
         std::string to_hex() const {
             auto clamp_byte = [](int v) -> int { return v < 0 ? 0 : (v > 255 ? 255 : v); };
@@ -66,7 +66,7 @@ namespace docraft {
         explicit DocraftColor(float r, float g, float b, float a = 1.0F);
 
         /**
-         * @brief Creates a color from a hex code (#RRGGBB or #RRGGBBAA).
+         * @brief Creates a color from a hex code (\#RRGGBB or \#RRGGBBAA).
          * @param hex_code Hex string.
          */
         explicit DocraftColor(const std::string &hex_code);

docraft/include/model/docraft_table.h

@@ -142,18 +142,21 @@ namespace docraft::model {
         /**
          * @brief Adds a title node.
          * @param node Title node.
+         * @param background Optional background color.
          */
         void add_title_node(const std::shared_ptr<DocraftText> &node,
                             std::optional<DocraftColor> background = std::nullopt);
         /**
          * @brief Adds a header title node (vertical tables only).
          * @param node Header title node.
+         * @param background Optional background color.
          */
         void add_htitle_node(const std::shared_ptr<DocraftText> &node,
                              std::optional<DocraftColor> background = std::nullopt);
         /**
          * @brief Adds a content node.
          * @param node Content node.
+         * @param background Optional background color.
          */
         void add_content_node(const std::shared_ptr<DocraftNode> &node,
                               std::optional<DocraftColor> background = std::nullopt);

docraft/include/templating/docraft_template_engine.h

@@ -31,29 +31,17 @@ namespace docraft::templating {
                  * @param value Variable value inserted into templates.
                  */
                 void add_template_variable(const std::string &name, const std::string &value);
-                /**
-                 * @brief Retrieves the value of a template variable by name.
-                 * @param name Name of the template variable.
-                 * @return Value of the template variable or empty string if not found.
-                 */
                 /**
                  * @brief Retrieves a template variable value.
                  * @param name Variable name (case-insensitive).
                  * @return Stored value.
                  * @throws std::runtime_error if not found.
                  */
                 std::string get_template_variable(const std::string &name);
-                /**
-                 * @brief Clears all template variables from the engine.
-                 */
                 /**
                  * @brief Clears all template variables.
                  */
                 void clear_template_variables();
-                /**
-                 * @brief Removes a specific template variable by name.
-                 * @param name Name of the template variable to remove.
-                 */
                 /**
                  * @brief Removes a template variable by name.
                  * @param name Variable name (case-insensitive).
@@ -64,11 +52,6 @@ namespace docraft::templating {
                  * @brief Returns the number of stored template variables.
                  */
                 int items() const;
-                /**
-                 * @brief Checks if a template variable exists by name.
-                 * @param name Name of the template variable.
-                 * @return True if the variable exists, false otherwise.
-                 */
                 /**
                  * @brief Checks if a template variable exists.
                  * @param name Variable name (case-insensitive).
@@ -86,7 +69,7 @@ namespace docraft::templating {
 
                 /**
                  * @brief Adds raw RGB image data.
-                 * @param image_id Image id used by <Image data="..."> in templates (case-insensitive).
+                 * @param image_id Image id used by \<Image data="..."\> in templates (case-insensitive).
                  * @param data Raw RGB bytes (3 bytes per pixel, row-major).
                  * @param width Pixel width.
                  * @param height Pixel height.
@@ -97,7 +80,7 @@ namespace docraft::templating {
                                     int height);
                 /**
                  * @brief Adds raw RGB image data from a base64 string.
-                 * @param image_id Image id used by <Image data="..."> in templates (case-insensitive).
+                 * @param image_id Image id used by \<Image data="..."\> in templates (case-insensitive).
                  * @param base64 Base64 string with raw RGB bytes (no data URI prefix).
                  * @param width Pixel width.
                  * @param height Pixel height.
@@ -123,6 +106,7 @@ namespace docraft::templating {
                  * @brief Renders a template string by replacing template variables with their values.
                  * @note input data = ${data("field_name")), json cannot have multiple levels of nested,
                  * @param text Template string to render.
+                 * @param item JSON object supplying per-iteration data for foreach loops.
                  * @return Rendered string with template variables replaced.
                  */
                 std::string render_template_string_foreach_item(const std::string &text,