cmake_minimum_required( VERSION 3.20 )

# ── Documentation (Doxygen) ─────────────────────────────────────────────────
#
# Adds the `docs` target:
#
#     cmake --build --preset conan-release --target docs
#
# It writes the HTML tree to  <build>/docs/html/  (open index.html): the
# README as the main page, the message-file reference (docs/syntax.md), the
# changelog, and the generator's internals (src/). ws-release.sh publishes
# that tree as the tenant's /api — the documentation site's reference part.
#
# Doxygen is optional: without it the `docs` target is simply not created and
# nothing else changes. Graphviz `dot`, also optional, enables the class /
# collaboration / include / call graphs.
#
# Pulled in by the root CMakeLists via add_subdirectory(docs).

find_package(Doxygen QUIET OPTIONAL_COMPONENTS dot)

if(NOT DOXYGEN_FOUND)
    message(STATUS "mstring: Doxygen not found — 'docs' target unavailable")
    return()
endif()

# CMakeLists carries a 4-part version (project(... VERSION 1.1.0.0)); the
# Doxygen tree and the release archives use the 3-part form.
#
# FORCE is load-bearing: set(... CACHE ...) without it is a no-op once the
# cache entry exists (ws-release.sh reuses build/Release/ across releases),
# so a version bump would silently not reach the generated docs.
set(DOXYGEN_PROJECT_NUMBER
    "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}"
    CACHE STRING "Version string shown in the Doxygen HTML header" FORCE)

set(DOXYGEN_SOURCE_DIR "${PROJECT_SOURCE_DIR}")
set(DOXYGEN_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}")   # -> <build>/docs/html/

if(TARGET Doxygen::dot)
    set(DOXYGEN_HAVE_DOT YES)
else()
    set(DOXYGEN_HAVE_DOT NO)
    message(STATUS "mstring: Graphviz 'dot' not found — dependency/call graphs disabled")
endif()

option(MSTRING_DOCS_WARN_AS_ERROR
       "Fail the 'docs' build on any Doxygen warning" OFF)
if(MSTRING_DOCS_WARN_AS_ERROR)
    set(DOXYGEN_WARN_AS_ERROR FAIL_ON_WARNINGS)
else()
    set(DOXYGEN_WARN_AS_ERROR NO)
endif()

configure_file("${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in"
               "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile" @ONLY)

add_custom_target(docs
    COMMAND ${CMAKE_COMMAND} -E make_directory "${DOXYGEN_OUTPUT_DIR}"
    COMMAND ${DOXYGEN_EXECUTABLE} "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
    WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}"
    COMMENT "Doxygen → ${DOXYGEN_OUTPUT_DIR}/html/index.html"
    VERBATIM)

message(STATUS "mstring: 'docs' target ready (Doxygen ${DOXYGEN_VERSION}, dot=${DOXYGEN_HAVE_DOT}) → ${DOXYGEN_PROJECT_NUMBER}")