docs(api): Move EVerest API asyncapi spec and build and provide HTMLs as part of EVerest doc (#1564)

* docs(api): Move asyncapi spec and provide HTMLs as part of EVerest doc
---------

Signed-off-by: Christoph Burandt <christoph.burandt@pionix.de>

Author: cburandt

CMakeLists.txt

@@ -63,7 +63,6 @@ endif()
 
 option(CREATE_SYMLINKS "Create symlinks to javascript modules and auxillary files - for development purposes" OFF)
 option(CMAKE_RUN_CLANG_TIDY "Run clang-tidy" OFF)
-option(EVEREST_BUILD_API_DOCS "Build EVerest API documentation" OFF)
 option(ISO15118_2_GENERATE_AND_INSTALL_CERTIFICATES "Automatically generate and install certificates for development purposes" ON)
 option(EVEREST_ENABLE_RUN_SCRIPT_GENERATION "Enables the generation of run scripts (convenience scripts for starting available configurations)" ON)
 option(EVEREST_BUILD_DOCS "Build EVerest documentation" OFF)

cmake/everest-generate.cmake

@@ -85,6 +85,36 @@ function(_ev_add_project)
         endif ()
     endif ()
 
+    # check for API
+    set(API_DIR "${EVEREST_PROJECT_DIR}/docs/source/reference/EVerest_API")
+    if (EXISTS ${API_DIR})
+        message(STATUS "Adding API definitions from ${API_DIR}")
+        file(GLOB API_FILES
+            ${API_DIR}/*.yaml
+        )
+
+        if(EVEREST_BUILD_DOCS)
+            find_package(
+                trailbook-ext-everest
+                0.1.0
+                REQUIRED
+                PATHS "${CMAKE_SOURCE_DIR}/cmake"
+            )
+            trailbook_ev_generate_api_doc(
+                TRAILBOOK_NAME "everest"
+                API_FILES ${API_FILES}
+            )
+        endif()
+
+        if (CALLED_FROM_WITHIN_PROJECT)
+            install(
+                DIRECTORY ${API_DIR}
+                DESTINATION "${CMAKE_INSTALL_DATADIR}/everest"
+                FILES_MATCHING PATTERN "*.yaml"
+            )
+        endif ()
+    endif ()
+
     # check for errors
     set(ERRORS_DIR "${EVEREST_PROJECT_DIR}/errors")
     if (EXISTS ${ERRORS_DIR})

cmake/fetch_async_api.cmake

@@ -8,6 +8,7 @@ The following additional features are provided:
 
 * cmake function: `trailbook_ev_add_module_explanation()`
 * cmake function: `trailbook_ev_create_snapshot()`
+* cmake function: `trailbook_ev_generate_api_doc()`
 * cmake function: `trailbook_ev_generate_rst_from_manifest()`
 * cmake function: `trailbook_ev_generate_rst_from_interface()`
 * cmake function: `trailbook_ev_generate_rst_from_types()`

cmake/fetch_async_api_html_template.cmake

@@ -0,0 +1,41 @@
+if(asyncapi-cli_DIR)
+    message(STATUS "Using asyncapi-cli at this location: ${asyncapi-cli_DIR}")
+else()
+    message(STATUS "Retrieving asyncapi-cli using FetchContent")
+    include(FetchContent)
+    FetchContent_Declare(
+      asyncapi-cli
+      GIT_REPOSITORY https://github.com/asyncapi/cli.git
+      GIT_TAG v2.7.1
+    )
+    FetchContent_MakeAvailable(asyncapi-cli)
+    set(asyncapi-cli_DIR "${asyncapi-cli_SOURCE_DIR}")
+    set(asyncapi-cli_FIND_COMPONENTS "bundling")
+endif()
+
+set(ASYNCAPI_CLI_INSTALL_SENTINEL_PATH "${CMAKE_CURRENT_BINARY_DIR}/generated")
+set(ASYNCAPI_CLI_INSTALL_SENTINEL "${ASYNCAPI_CLI_INSTALL_SENTINEL_PATH}/asyncapi_cli_install_done")
+
+if(NOT TARGET asyncapi_cli_install_target)
+    add_custom_command(
+        OUTPUT ${ASYNCAPI_CLI_INSTALL_SENTINEL}
+
+        # Do installation
+        COMMAND ${CMAKE_COMMAND} -E chdir ${asyncapi-cli_DIR} npm install
+        COMMAND ${CMAKE_COMMAND} -E chdir ${asyncapi-cli_DIR} npm run build
+
+        # Create sentinel file
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${ASYNCAPI_CLI_INSTALL_SENTINEL_PATH}
+        COMMAND ${CMAKE_COMMAND} -E touch ${ASYNCAPI_CLI_INSTALL_SENTINEL}
+
+        COMMENT "AsyncApi/cli Install once only"
+    )
+
+    add_custom_target(asyncapi_cli_install_target
+        DEPENDS ${ASYNCAPI_CLI_INSTALL_SENTINEL}
+    )
+else()
+    message(STATUS "Skipping definition of 'asyncapi_cli_install_target'; already exists.")
+endif()
+
+set(ASYNCAPI_CMD ${asyncapi-cli_DIR}/bin/run)

cmake/generate-api-docs.cmake

@@ -0,0 +1,45 @@
+if(asyncapi-html-template_DIR)
+    message(STATUS "Using existing asyncapi-html-template location: ${asyncapi-html-template_DIR}")
+else()
+    find_package(asyncapi-html-template
+        COMPONENTS bundling
+        PATHS ../asyncapi-html-template
+    )
+
+    if(NOT asyncapi-html-template_FOUND)
+        message(STATUS "Retrieving asyncapi-html-template using FetchContent")
+        include(FetchContent)
+        FetchContent_Declare(
+          asyncapi-html-template
+          GIT_REPOSITORY https://github.com/asyncapi/html-template.git
+          GIT_TAG v3.0.0
+        )
+        FetchContent_MakeAvailable(asyncapi-html-template)
+        set(asyncapi-html-template_DIR "${asyncapi-html-template_SOURCE_DIR}")
+        set(asyncapi-html-template_FIND_COMPONENTS "bundling")
+    endif()
+endif()
+
+set(ASYNCAPI_HTML_TEMPLATE_INSTALL_SENTINEL_PATH "${CMAKE_CURRENT_BINARY_DIR}/generate")
+set(ASYNCAPI_HTML_TEMPLATE_INSTALL_SENTINEL "${ASYNCAPI_HTML_TEMPLATE_INSTALL_SENTINEL_PATH}/asyncapi_html_template_install_done")
+
+if(NOT TARGET asyncapi_html_template_install_target)
+    add_custom_command(
+        OUTPUT ${ASYNCAPI_HTML_TEMPLATE_INSTALL_SENTINEL}
+
+        # Do installation
+        COMMAND ${CMAKE_COMMAND} -E chdir ${asyncapi-html-template_DIR} npm install
+
+        # Create sentinel file
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${ASYNCAPI_HTML_TEMPLATE_INSTALL_SENTINEL_PATH}
+        COMMAND ${CMAKE_COMMAND} -E touch ${ASYNCAPI_HTML_TEMPLATE_INSTALL_SENTINEL}
+
+        COMMENT "AsyncApi/html-template Install once only"
+    )
+
+    add_custom_target(asyncapi_html_template_install_target
+        DEPENDS ${ASYNCAPI_HTML_TEMPLATE_INSTALL_SENTINEL}
+    )
+else()
+    message(STATUS "Skipping definition of 'asyncapi_html_template_install_target'; already exists.")
+endif()