New EVerest documentation

CMakeLists.txt

@@ -63,9 +63,10 @@ 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)
+option(EVEREST_SKIP_BUILD_API_DOC "Skip building the async API html doc for the EVerest API" OFF)
 option(${PROJECT_NAME}_BUILD_TESTING "Build unit tests, used if included as dependency" OFF)
 option(BUILD_TESTING "Build unit tests, used if standalone project" OFF)
 option(EVEREST_ENABLE_COMPILE_WARNINGS "Enable compile warnings set in the EVEREST_COMPILE_OPTIONS flag" OFF)
@@ -176,6 +177,9 @@ else()
     find_package(OpenSSL 3 REQUIRED)
 endif()
 
+if(EVEREST_BUILD_DOCS)
+    add_subdirectory(docs)
+endif()
 
 include(ev-project-bootstrap)
 
@@ -192,8 +196,6 @@ add_subdirectory(lib)
 # FIXME (aw): this should be optional
 add_subdirectory(config)
 
-add_subdirectory(doc)
-
 if(EVEREST_BUILD_APPLICATIONS)
   add_subdirectory(applications)
 endif()

THIRD_PARTY.md

@@ -2,3 +2,4 @@
 
 - [CodeCoverage.cmake](https://github.com/bilke/cmake-modules/blob/master/CodeCoverage.cmake) licensed under [The 3-Clause BSD License](https://opensource.org/licenses/BSD-3-Clause)
 - [Nanopb - Protocol Buffers for Embedded Systems](https://github.com/nanopb/nanopb) licensed under [The zlib License](https://opensource.org/licenses/Zlib)
+- [sphinx-notfound-page](https://github.com/readthedocs/sphinx-notfound-page) licensed under [The MIT License](https://opensource.org/licenses/MIT)

cmake/everest-generate.cmake

@@ -59,6 +59,21 @@ function(_ev_add_project)
             ${TYPES_DIR}/*.yaml
         )
 
+        if(EVEREST_BUILD_DOCS)
+            find_package(
+                trailbook-ext-everest
+                0.1.0
+                REQUIRED
+                PATHS "${CMAKE_SOURCE_DIR}/cmake"
+            )
+            foreach(TYPES_FILE ${TYPES_FILES})
+                trailbook_ev_generate_rst_from_types(
+                    TRAILBOOK_NAME "everest"
+                    TYPES_FILE "${TYPES_FILE}"
+                )
+            endforeach()
+        endif()
+
         _ev_add_types(${TYPES_FILES})
 
         if (CALLED_FROM_WITHIN_PROJECT)
@@ -70,6 +85,40 @@ function(_ev_add_project)
         endif ()
     endif ()
 
+    # check for API
+    set(API_DIR "${EVEREST_PROJECT_DIR}/docs/source/reference/EVerest_API")
+    if (EXISTS ${API_DIR})
+        if (${EVEREST_SKIP_BUILD_API_DOC})
+            message(WARNING "Skipping the generation of the EVerest API AsyncAPI html documentation")
+        else()
+            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 ()
+    endif ()
+
     # check for errors
     set(ERRORS_DIR "${EVEREST_PROJECT_DIR}/errors")
     if (EXISTS ${ERRORS_DIR})
@@ -91,6 +140,21 @@ function(_ev_add_project)
             ${INTERFACES_DIR}/*.yaml
         )
 
+        if(EVEREST_BUILD_DOCS)
+            find_package(
+                trailbook-ext-everest
+                0.1.0
+                REQUIRED
+                PATHS "${CMAKE_SOURCE_DIR}/cmake"
+            )
+            foreach(INTERFACE_FILE ${INTERFACE_FILES})
+                trailbook_ev_generate_rst_from_interface(
+                    TRAILBOOK_NAME "everest"
+                    INTERFACE_FILE "${INTERFACE_FILE}"
+                )
+            endforeach()
+        endif()
+
         _ev_add_interfaces(${INTERFACE_FILES})
 
         if (CALLED_FROM_WITHIN_PROJECT)
@@ -420,6 +484,36 @@ function (ev_add_module)
         endforeach()
     endif()
 
+    if (EVEREST_BUILD_DOCS)
+        find_package(
+            trailbook-ext-everest
+            0.1.0
+            REQUIRED
+            PATHS "${CMAKE_SOURCE_DIR}/cmake"
+        )
+        if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/docs/")
+            trailbook_ev_add_module_explanation(
+                TRAILBOOK_NAME "everest"
+                MODULE_NAME "${MODULE_NAME}"
+                EXPLANATION_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/docs"
+            )
+        endif()
+        if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/doc.rst")
+            message(
+                FATAL_ERROR
+                "Module ${MODULE_NAME} contains a doc.rst file"
+                " this is not supported anymore, please move to"
+                " docs/index.rst, then it will be picked up automatically."
+                " For now this file will be ignored."
+            )
+        endif()
+        trailbook_ev_generate_rst_from_manifest(
+            TRAILBOOK_NAME "everest"
+            MANIFEST_FILE "${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/manifest.yaml"
+        )
+    endif()
+
+
     # check if python module
     string(FIND ${MODULE_NAME} "Py" MODULE_PREFIX_POS)
     if (MODULE_PREFIX_POS EQUAL 0)

cmake/trailbook-ext-everest/README.md

@@ -0,0 +1,18 @@
+# Trailbook Extension for Everest
+
+This CMake package is an extension for the Trailbook CMake package
+that provides additional functionality specifically for building
+documentation for the Everest project.
+
+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()`
+
+Check out the inline documentation of the functions for more details
+on how to use them. Each function is defined in its own CMake file
+located in this package directory.