cmake_minimum_required( VERSION 3.20 )

# ── API documentation (Doxygen) ─────────────────────────────────────────────
#
# Adds the `docs` target:
#
#     cmake -B build
#     cmake --build build --target docs
#
# It writes the HTML tree to  <build>/docs/html/  (open index.html). That same
# tree is published at https://plugin.fedem.eu/api — drop it into the deployed
# tenant with:
#
#     rm -rf   <ffs-projects>/plugin/static/api
#     mkdir -p <ffs-projects>/plugin/static/api
#     cp -r    build/docs/html/. <ffs-projects>/plugin/static/api/
#
# The hand-written companion is the Reference Manual at /reference; the CLI
# signing tools are documented at /tools.
#
# Doxygen is optional: if it is not installed the `docs` target is simply not
# created and nothing else changes. Graphviz `dot`, also optional, enables the
# class / collaboration / include / call / caller graphs.
#
# This file is pulled in by the root CMakeLists via add_subdirectory(docs),
# but only when plugin is the top-level project (PLUGIN_STANDALONE) — an
# embedding host (FFS) would collide on the `docs` target name.

# PROJECT_SOURCE_DIR points at the plugin repo root whether this is built as a
# subdirectory or configured on its own (cmake -S docs -B ...).
if(NOT DEFINED PROJECT_SOURCE_DIR OR NOT EXISTS "${PROJECT_SOURCE_DIR}/src/plugin/Plugin.hh")
    get_filename_component(PROJECT_SOURCE_DIR "${CMAKE_CURRENT_LIST_DIR}/.." ABSOLUTE)
endif()

find_package(Doxygen QUIET OPTIONAL_COMPONENTS dot)

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

# CMakeLists.txt carries a 4-part version (project(... VERSION 2.1.1.0)); the
# Doxygen tree and the release archives use the 3-part form.
if(DEFINED PROJECT_VERSION_MAJOR)
    set(_plugin_doxy_default_number
        "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}")
else()
    set(_plugin_doxy_default_number "")
endif()
# FORCE is load-bearing, not decorative: set(... CACHE ...) without it is a
# no-op once the cache entry already exists (e.g. ws-release.sh reuses
# build/Release/ across releases), so a version bump would silently NOT reach
# the generated docs — the previous release's number would keep showing
# forever. FORCE means this can no longer be overridden with
# -DDOXYGEN_PROJECT_NUMBER=... (the comment here used to advertise that;
# nothing relied on it).
set(DOXYGEN_PROJECT_NUMBER "${_plugin_doxy_default_number}" CACHE STRING
    "Version string shown in the Doxygen HTML header" FORCE)

# What to scan: the three library modules (dso/, plugin/, sign/) and the
# dso-keygen / dso-sign / dso-verify CLI sources. The Shape example under
# example/ is walked through on the site (/examples, /walkthrough) rather than
# by Doxygen.
set(DOXYGEN_INPUT_DIR
    "\"${PROJECT_SOURCE_DIR}/src\" \"${PROJECT_SOURCE_DIR}/apps/src\"")
set(DOXYGEN_STRIP_FROM_PATH "${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 "plugin: Graphviz 'dot' not found — dependency/call graphs disabled")
endif()

option(PLUGIN_DOCS_WARN_AS_ERROR
       "Fail the 'docs' build on any Doxygen warning" OFF)
if(PLUGIN_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 "plugin: 'docs' target ready (Doxygen ${DOXYGEN_VERSION}, dot=${DOXYGEN_HAVE_DOT}) → ${DOXYGEN_PROJECT_NUMBER}")