eric/cariflex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
cariflex/tools/EVerest-main/cmake/trailbook/add-trailbook.cmake
Eric F d398a6ced2 Add extracted tools: CitrineOS, OpenOCPP, ShapeShifter 
- CitrineOS core extracted (CSMS OCPP 2.0.1)
- OpenOCPP extracted (firmware OCPP 1.6J/2.0.1)
- ShapeShifter library installed (pip install -e)
- ShapeShifter specification extracted
- EVerest extracted

TODO updated with progress
2026-06-08 00:38:27 -04:00

722 lines
32 KiB
CMake
Raw Permalink Blame History

# This macro is for internal use only
#
# It is used in the function add_trailbook.
# It checks the requirements defined by the requirements.txt file
# and installs any missing packages into the current Python virtual environment.
# It checks during the configuration phase.
macro(_add_trailbook_check_requirements_txt)
if(EXISTS ${args_REQUIREMENTS_TXT})
execute_process(
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/check_requirements_txt.py
${args_REQUIREMENTS_TXT}
--fix-in-venv
RESULT_VARIABLE _CHECK_REQUIREMENTS_TXT_RESULT
)
if(NOT _CHECK_REQUIREMENTS_TXT_RESULT EQUAL 0)
message(FATAL_ERROR "Trailbook: ${args_NAME} - ${args_REQUIREMENTS_TXT} not satisfied.")
else()
message(STATUS "Trailbook: ${args_NAME} - ${args_REQUIREMENTS_TXT} satisfied.")
endif()
else()
message(STATUS "Trailbook: ${args_NAME} - No requirements.txt found.")
endif()
endmacro()
# This macro is for internal use only
#
# It is used in the function add_trailbook.
# It sets up the trailbook build directory where the multiversion HTML docs will be located.
# If TRAILBOOK_INSTANCE_DOWNLOAD_ALL_VERSIONS is ON, it clones the deployed docs repo.
# Otherwise, it creates an empty skeleton directory.
# This configuration is checked during the configuration phase and should not be switched
macro(_add_trailbook_setup_build_directory)
set(CHECK_DONE_FILE_SETUP_BUILD_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/setup_build_directory.check_done")
set(SETUP_BUILD_DIRECTORY_FILE_LIST "${CMAKE_CURRENT_BINARY_DIR}/setup_build_directory_filelist.yaml")
set(DEPLOYED_DOCS_REPO_DIR "${CMAKE_CURRENT_BINARY_DIR}/deployed_docs_repo/")
if(TRAILBOOK_INSTANCE_DOWNLOAD_ALL_VERSIONS)
if(_SETUP_BUILD_DIRECTORY_LAST_CONFIGURATION STREQUAL "EMPTY_SKELETON")
message(FATAL_ERROR "add_trailbook: Cannot switch between DOWNLOAD_ALL_VERSIONS and EMPTY_SKELETON configurations for trailbook ${args_NAME} without cleaning build directory")
endif()
else()
if(_SETUP_BUILD_DIRECTORY_LAST_CONFIGURATION STREQUAL "DOWNLOAD_ALL_VERSIONS")
message(FATAL_ERROR "add_trailbook: Cannot switch between DOWNLOAD_ALL_VERSIONS and EMPTY_SKELETON configurations for trailbook ${args_NAME} without cleaning build directory")
endif()
endif()
if(TRAILBOOK_INSTANCE_DOWNLOAD_ALL_VERSIONS)
find_program(
GIT_EXECUTABLE
NAMES git
REQUIRED
)
set(CONDITIONAL_DELETE_LATEST_DIR_COMMAND "")
if(TRAILBOOK_INSTANCE_IS_RELEASE)
set(CONDITIONAL_DELETE_LATEST_DIR_COMMAND
COMMAND
${CMAKE_COMMAND} -E rm -rf
${CMAKE_CURRENT_BINARY_DIR}/tmp_repo_download/docs/latest
)
endif()
set(CONDITIONAL_DELETE_INSTANCE_DIR_OR_FAIL_COMMAND "")
if(TRAILBOOK_${args_NAME}_OVERWRITE_EXISTING_INSTANCE)
set(CONDITIONAL_DELETE_INSTANCE_DIR_OR_FAIL_COMMAND
COMMAND
${CMAKE_COMMAND} -E rm -rf
${CMAKE_CURRENT_BINARY_DIR}/tmp_repo_download/docs/${TRAILBOOK_${args_NAME}_INSTANCE_NAME}
)
else()
# check if instance directory already exists and fail if it does
set(CONDITIONAL_DELETE_INSTANCE_DIR_OR_FAIL_COMMAND
COMMAND
${Python3_EXECUTABLE} ${CMAKE_CURRENT_FUNCTION_LIST_DIR}/check_path_exists.py
--directory ${CMAKE_CURRENT_BINARY_DIR}/tmp_repo_download/docs/${TRAILBOOK_${args_NAME}_INSTANCE_NAME}
--return-zero-if-not-exists
)
endif()
add_custom_command(
OUTPUT
${CHECK_DONE_FILE_SETUP_BUILD_DIRECTORY}
DEPENDS
trailbook_${args_NAME}_stage_prepare_sphinx_source_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_PREPARE_SPHINX_SOURCE_BEFORE>
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
${Python3_EXECUTABLE} ${CMAKE_CURRENT_FUNCTION_LIST_DIR}/check_path_exists.py
COMMENT
"Trailbook: ${args_NAME} - Downloading all versions repo"
COMMAND # Remove existing files in deployed docs repo directory from previous builds
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
remove
--data-file ${SETUP_BUILD_DIRECTORY_FILE_LIST}
--root-directory ${DEPLOYED_DOCS_REPO_DIR}
COMMAND # Clone deployed docs repo
${GIT_EXECUTABLE} clone
-b ${args_DEPLOYED_DOCS_REPO_BRANCH}
--depth 1
${args_DEPLOYED_DOCS_REPO_URL}
${CMAKE_CURRENT_BINARY_DIR}/tmp_repo_download/
# Remove latest directory if this is a release instance
${CONDITIONAL_DELETE_LATEST_DIR_COMMAND}
# Remove existing instance directory if overwrite is enabled or fail if it exists
${CONDITIONAL_DELETE_INSTANCE_DIR_OR_FAIL_COMMAND}
COMMAND # Create file list of existing files in deployed docs repo directory after clone
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
create
--data-file ${SETUP_BUILD_DIRECTORY_FILE_LIST}
--root-directory ${CMAKE_CURRENT_BINARY_DIR}/tmp_repo_download
COMMAND # Move cloned files to deployed docs repo directory
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
move
--data-file ${SETUP_BUILD_DIRECTORY_FILE_LIST}
--root-directory ${CMAKE_CURRENT_BINARY_DIR}/tmp_repo_download
--target-root-directory ${DEPLOYED_DOCS_REPO_DIR}/
COMMAND # Delete temporary clone directory
${CMAKE_COMMAND} -E rm -rf
${CMAKE_CURRENT_BINARY_DIR}/tmp_repo_download/
COMMAND # Create convenience symlink to docs/ in build directory
${CMAKE_COMMAND} -E create_symlink
${DEPLOYED_DOCS_REPO_DIR}/docs/
${TRAILBOOK_BUILD_DIRECTORY}
COMMAND # Create done file
${CMAKE_COMMAND} -E touch ${CHECK_DONE_FILE_SETUP_BUILD_DIRECTORY}
)
set(_SETUP_BUILD_DIRECTORY_LAST_CONFIGURATION "DOWNLOAD_ALL_VERSIONS")
else()
set(CONDITIONAL_CLEANUP_COMMAND "")
add_custom_command(
OUTPUT
${CHECK_DONE_FILE_SETUP_BUILD_DIRECTORY}
DEPENDS
trailbook_${args_NAME}_stage_prepare_sphinx_source_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_PREPARE_SPHINX_SOURCE_BEFORE>
COMMENT
"Trailbook: ${args_NAME} - Creating empty skeleton multiversion root directory"
COMMAND
${CMAKE_COMMAND} -E make_directory
${TRAILBOOK_BUILD_DIRECTORY}/
COMMAND
${CMAKE_COMMAND} -E touch ${CHECK_DONE_FILE_SETUP_BUILD_DIRECTORY}
)
set(_SETUP_BUILD_DIRECTORY_LAST_CONFIGURATION "EMPTY_SKELETON")
endif()
endmacro()
# This macro is for internal use only
#
# It is used in the function add_trailbook.
# It adds a custom command to copy the trailbook stem files to the build directory.
# To be used a base for the tailbook instance source directory.
macro(_add_trailbook_copy_stem_command)
file(
GLOB_RECURSE
STEM_FILES_SOURCE_DIR
CONFIGURE_DEPENDS
"${args_STEM_DIRECTORY}/*"
)
set(STEM_FILES_BUILD_DIR "")
foreach(file_path IN LISTS STEM_FILES_SOURCE_DIR)
file(RELATIVE_PATH rel_path "${args_STEM_DIRECTORY}" "${file_path}")
list(APPEND STEM_FILES_BUILD_DIR "${TRAILBOOK_INSTANCE_SOURCE_DIRECTORY}/${rel_path}")
endforeach()
add_custom_command(
OUTPUT
${STEM_FILES_BUILD_DIR}
DEPENDS
${STEM_FILES_SOURCE_DIR}
trailbook_${args_NAME}_stage_prepare_sphinx_source_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_PREPARE_SPHINX_SOURCE_BEFORE>
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
COMMENT
"Trailbook: ${args_NAME} - Copying stem files to build directory"
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
remove
--data-file ${CMAKE_CURRENT_BINARY_DIR}/copy_stem_filelist.yaml
--root-directory ${TRAILBOOK_INSTANCE_SOURCE_DIRECTORY}
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
create
--data-file ${CMAKE_CURRENT_BINARY_DIR}/copy_stem_filelist.yaml
--root-directory ${args_STEM_DIRECTORY}
COMMAND
${CMAKE_COMMAND} -E copy_directory
${args_STEM_DIRECTORY}
${TRAILBOOK_INSTANCE_SOURCE_DIRECTORY}
)
endmacro()
# This macro is for internal use only
#
# It is used in the function add_trailbook.
# It adds a custom command to create the metadata YAML file for the trailbook instance.
# The metadata YAML file is used by Sphinx during the build process.
# It contains a list of all versions available in the multiversion root directory.
macro(_add_trailbook_create_metadata_yaml_command)
set(METADATA_YAML_FILE "${CMAKE_CURRENT_BINARY_DIR}/metadata_${args_NAME}.yaml")
add_custom_command(
OUTPUT
${METADATA_YAML_FILE}
DEPENDS
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/create_metadata_yaml.py
${STEM_FILES_BUILD_DIR}
${CHECK_DONE_FILE_SETUP_BUILD_DIRECTORY}
trailbook_${args_NAME}_stage_prepare_sphinx_source_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_PREPARE_SPHINX_SOURCE_BEFORE>
COMMENT
"Trailbook: ${args_NAME} - Creating metadata YAML file"
COMMAND
${CMAKE_COMMAND} -E rm -f ${METADATA_YAML_FILE}
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/create_metadata_yaml.py
--multiversion-root-directory "${TRAILBOOK_BUILD_DIRECTORY}"
"--output-path" "${METADATA_YAML_FILE}"
--additional-version "${TRAILBOOK_${args_NAME}_INSTANCE_NAME}"
)
endmacro()
# This macro is for internal use only
#
# It is used in the function add_trailbook.
# It adds a custom command to build the Sphinx HTML documentation for the trailbook instance.
# It builds from the trailbook instance source directory to the trailbook instance build directory.
macro(_add_trailbook_sphinx_build_command)
set(CHECK_DONE_FILE_SPHINX_BUILD_COMMAND "${CMAKE_CURRENT_BINARY_DIR}/build_html.check_done")
add_custom_command(
OUTPUT
${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
DEPENDS
trailbook_${args_NAME}_stage_build_sphinx_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_BUILD_SPHINX_BEFORE>
${STEM_FILES_BUILD_DIR}
${METADATA_YAML_FILE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
COMMENT
"Trailbook: ${args_NAME} - Building HTML documentation with Sphinx"
USES_TERMINAL
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
remove
--data-file ${CMAKE_CURRENT_BINARY_DIR}/sphinx_build_filelist.yaml
--root-directory ${TRAILBOOK_INSTANCE_BUILD_DIRECTORY}/
COMMAND
EVEREST_METADATA_YAML_PATH=${METADATA_YAML_FILE}
${_SPHINX_BUILD_EXECUTABLE}
-b html
${TRAILBOOK_INSTANCE_SOURCE_DIRECTORY}
${CMAKE_CURRENT_BINARY_DIR}/sphinx_build_temp/
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
create
--data-file ${CMAKE_CURRENT_BINARY_DIR}/sphinx_build_filelist.yaml
--root-directory ${CMAKE_CURRENT_BINARY_DIR}/sphinx_build_temp/
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/filelist_manager.py
move
--data-file ${CMAKE_CURRENT_BINARY_DIR}/sphinx_build_filelist.yaml
--root-directory ${CMAKE_CURRENT_BINARY_DIR}/sphinx_build_temp/
--target-root-directory ${TRAILBOOK_INSTANCE_BUILD_DIRECTORY}/
COMMAND
${CMAKE_COMMAND} -E echo
"Trailbook: ${args_NAME} - HTML documentation built at ${TRAILBOOK_INSTANCE_BUILD_DIRECTORY}"
COMMAND
${CMAKE_COMMAND} -E touch ${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
)
endmacro()
# This macro is for internal use only
#
# It is used in the function add_trailbook.
# It adds a custom command to replace the 'latest' copy in the multiversion root directory
# It should be only called if TRAILBOOK_INSTANCE_IS_RELEASE is ON.
macro(_add_trailbook_replace_latest_command)
set(CHECK_DONE_FILE_REPLACE_LATEST "${CMAKE_CURRENT_BINARY_DIR}/replace_latest.check_done")
add_custom_command(
OUTPUT
${CHECK_DONE_FILE_REPLACE_LATEST}
DEPENDS
trailbook_${args_NAME}_stage_postprocess_sphinx_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_POSTPROCESS_SPHINX_BEFORE>
${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
COMMENT
"Trailbook: ${args_NAME} - Replacing 'latest' copy with copy of current instance"
COMMAND
${CMAKE_COMMAND} -E rm -rf ${TRAILBOOK_BUILD_DIRECTORY}/latest
COMMAND
${CMAKE_COMMAND} -E copy_directory
${TRAILBOOK_INSTANCE_BUILD_DIRECTORY}
${TRAILBOOK_BUILD_DIRECTORY}/latest
COMMAND
${CMAKE_COMMAND} -E touch ${CHECK_DONE_FILE_REPLACE_LATEST}
)
endmacro()
# This macro is for internal use only
#
# It is used in the function add_trailbook.
# It copies the 404.html file from the trailbook instance build directory
# to the multiversion root directory.
# It should only be called if TRAILBOOK_INSTANCE_IS_RELEASE is ON.
macro(_add_trailbook_copy_404_command)
set(CHECK_DONE_FILE_COPY_404 "${CMAKE_CURRENT_BINARY_DIR}/copy_404.check_done")
set(TRAILBOOK_404_FILE "${TRAILBOOK_BUILD_DIRECTORY}/404.html")
set(TRAILBOOK_INSTANCE_404_FILE "${TRAILBOOK_INSTANCE_BUILD_DIRECTORY}/404.html")
add_custom_command(
OUTPUT
${TRAILBOOK_INSTANCE_404_FILE}
DEPENDS
trailbook_${args_NAME}_stage_postprocess_sphinx_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_POSTPROCESS_SPHINX_BEFORE>
${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/check_path_exists.py
COMMENT
"Trailbook: ${args_NAME} - Checking for 404.html in built documentation"
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/check_path_exists.py
--file "${TRAILBOOK_INSTANCE_404_FILE}"
--return-zero-if-exists
)
add_custom_command(
OUTPUT
${CHECK_DONE_FILE_COPY_404}
DEPENDS
trailbook_${args_NAME}_stage_postprocess_sphinx_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_POSTPROCESS_SPHINX_BEFORE>
${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
${TRAILBOOK_INSTANCE_404_FILE}
COMMENT
"Trailbook: ${args_NAME} - Copying 404.html to multiversion root directory"
COMMAND
${CMAKE_COMMAND} -E rm -f ${TRAILBOOK_404_FILE}
COMMAND
${CMAKE_COMMAND} -E copy
${TRAILBOOK_INSTANCE_404_FILE}
${TRAILBOOK_404_FILE}
COMMAND
${CMAKE_COMMAND} -E touch ${CHECK_DONE_FILE_COPY_404}
)
endmacro()
# This macro is for internal use only
#
# It is used in the function add_tailbook.
# It adds a custom command to render the redirect template. The rendered file
# will be used as the index.html in the multiversion root directory.
# This macro should only be called if TRAILBOOK_INSTANCE_IS_RELEASE is ON.
macro(_add_trailbook_render_redirect_template_command)
set(CHECK_DONE_FILE_RENDER_REDIRECT_TEMPLATE "${CMAKE_CURRENT_BINARY_DIR}/render_redirect_template.check_done")
set(REDIRECT_TEMPLATE_FILE "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/templates/redirect.html.jinja")
set(TRAILBOOK_REDIRECT_FILE "${TRAILBOOK_BUILD_DIRECTORY}/index.html")
add_custom_command(
OUTPUT
${CHECK_DONE_FILE_RENDER_REDIRECT_TEMPLATE}
DEPENDS
trailbook_${args_NAME}_stage_postprocess_sphinx_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_POSTPROCESS_SPHINX_BEFORE>
${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/render_redirect_template.py
COMMENT
"Trailbook: ${args_NAME} - Rendering redirect.html from template"
COMMAND
${CMAKE_COMMAND} -E rm -f ${TRAILBOOK_REDIRECT_FILE}
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/render_redirect_template.py
--redirect-template "${REDIRECT_TEMPLATE_FILE}"
"--target-path" "${TRAILBOOK_REDIRECT_FILE}"
COMMAND
${CMAKE_COMMAND} -E touch ${CHECK_DONE_FILE_RENDER_REDIRECT_TEMPLATE}
)
endmacro()
# This macro is for internal use only
#
# It is used in the function add_trailbook.
# It adds a custom command to copy the versions_index.html file to the multiversion root directory
macro(_add_trailbook_copy_versions_index_command)
set(CHECK_DONE_FILE_COPY_VERSIONS_INDEX "${CMAKE_CURRENT_BINARY_DIR}/copy_versions_index.check_done")
set(TRAILBOOK_VERSIONS_INDEX_FILE "${TRAILBOOK_BUILD_DIRECTORY}/versions_index.html")
set(TRAILBOOK_INSTANCE_VERSIONS_INDEX_FILE "${TRAILBOOK_INSTANCE_BUILD_DIRECTORY}/versions_index.html")
set(CHECK_DONE_FILE_CHECK_LATEST_INSTANCE "${CMAKE_CURRENT_BINARY_DIR}/check_latest_instance.check_done")
add_custom_command(
OUTPUT
${TRAILBOOK_INSTANCE_VERSIONS_INDEX_FILE}
DEPENDS
trailbook_${args_NAME}_stage_postprocess_sphinx_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_POSTPROCESS_SPHINX_BEFORE>
${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/check_path_exists.py
COMMENT
"Trailbook: ${args_NAME} - Checking for versions_index.html in built documentation"
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/check_path_exists.py
--file "${TRAILBOOK_INSTANCE_VERSIONS_INDEX_FILE}"
--return-zero-if-exists
)
add_custom_command(
OUTPUT
${CHECK_DONE_FILE_CHECK_LATEST_INSTANCE}
DEPENDS
trailbook_${args_NAME}_stage_postprocess_sphinx_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_POSTPROCESS_SPHINX_BEFORE>
${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
${CHECK_DONE_FILE_REPLACE_LATEST}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/check_path_exists.py
COMMENT
"Trailbook: ${args_NAME} - Checking for latest/ in multiversion root directory"
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/check_path_exists.py
--directory ${TRAILBOOK_BUILD_DIRECTORY}/latest
--return-zero-if-exists
COMMAND
${CMAKE_COMMAND} -E touch ${CHECK_DONE_FILE_CHECK_LATEST_INSTANCE}
)
add_custom_command(
OUTPUT
${CHECK_DONE_FILE_COPY_VERSIONS_INDEX}
DEPENDS
trailbook_${args_NAME}_stage_postprocess_sphinx_before
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_POSTPROCESS_SPHINX_BEFORE>
${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
${TRAILBOOK_INSTANCE_VERSIONS_INDEX_FILE}
${CHECK_DONE_FILE_CHECK_LATEST_INSTANCE}
COMMENT
"Trailbook: ${args_NAME} - Copying versions_index.html to multiversion root directory"
COMMAND
${CMAKE_COMMAND} -E rm -f ${TRAILBOOK_VERSIONS_INDEX_FILE}
COMMAND
${CMAKE_COMMAND} -E copy
${TRAILBOOK_INSTANCE_VERSIONS_INDEX_FILE}
${TRAILBOOK_VERSIONS_INDEX_FILE}
COMMAND
${CMAKE_COMMAND} -E touch ${CHECK_DONE_FILE_COPY_VERSIONS_INDEX}
)
endmacro()
# This macro is for internal use only
#
# It is used in the function add_tailbook.
# It adds a custom target to serve the built HTML documentation via a simple HTTP server.
macro(_add_trailbook_preview_target)
add_custom_target(
trailbook_${args_NAME}_preview
DEPENDS
trailbook_${args_NAME}
COMMENT
"Trailbook: ${args_NAME} - Serve HTML documentation"
USES_TERMINAL
COMMAND
${CMAKE_COMMAND} -E echo
"Trailbook: ${args_NAME} - Serving HTML output at http://localhost:8000/"
COMMAND
${Python3_EXECUTABLE} -m http.server --directory ${TRAILBOOK_BUILD_DIRECTORY} 8000
)
endmacro()
# This macro is for internal use only
#
# It is used in the function add_tailbook.
# It adds a custom target to watch the trailbook instance target for changes
# and automatically rebuild the HTML documentation with Sphinx and serve it.
macro(_add_trailbook_live_preview_target)
add_custom_target(
trailbook_${args_NAME}_live_preview
DEPENDS
trailbook_${args_NAME}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/target_observer.py
COMMENT
"Trailbook: ${args_NAME} - Auto-build HTML documentation with Sphinx and serve"
USES_TERMINAL
COMMAND
${CMAKE_COMMAND} -E echo
"Trailbook: ${args_NAME} - Auto-building HTML output and serving at http://localhost:8000/"
COMMAND
${Python3_EXECUTABLE}
${CMAKE_CURRENT_FUNCTION_LIST_DIR}/target_observer.py
"trailbook_${args_NAME}"
"trailbook_${args_NAME}_preview"
--build-dir ${CMAKE_BINARY_DIR}
--interval-ms 2000
)
endmacro()
# This is the main function to add a trailbook to the build system.
# It sets up the necessary build commands and targets
# to build the trailbook documentation.
# It takes the following parameters:
# NAME (required): The name of the trailbook.
# STEM_DIRECTORY (optional): The directory containing the trailbook stem files.
# Defaults to CMAKE_CURRENT_SOURCE_DIR.
# REQUIREMENTS_TXT (optional): The path to the requirements.txt file.
# Defaults to CMAKE_CURRENT_SOURCE_DIR/requirements.txt if exists.
# INSTANCE_NAME (required): The instance name for the trailbook.
# Needs to be lowercase alphanumeric and underscores only.
# DEPLOYED_DOCS_REPO_URL (optional): The URL of the deployed docs repository.
# Required if TRAILBOOK_<NAME>_DOWNLOAD_ALL_VERSIONS is ON.
# DEPLOYED_DOCS_REPO_BRANCH (optional): The branch of the deployed docs repository.
# Defaults to 'main'.
# Usage:
# add_trailbook(
# NAME <trailbook_name>
# [STEM_DIRECTORY <stem_directory>]
# [REQUIREMENTS_TXT <requirements_txt_path>]
# INSTANCE_NAME <instance_name>
# [DEPLOYED_DOCS_REPO_URL <deployed_docs_repo_url>]
# [DEPLOYED_DOCS_REPO_BRANCH <deployed_docs_repo_branch>]
# )
function(add_trailbook)
set(options)
set(one_value_args
NAME
STEM_DIRECTORY
REQUIREMENTS_TXT
DEPLOYED_DOCS_REPO_URL
DEPLOYED_DOCS_REPO_BRANCH
)
set(multi_value_args)
cmake_parse_arguments(
"args"
"${options}"
"${one_value_args}"
"${multi_value_args}"
${ARGN}
)
option(TRAILBOOK_${args_NAME}_DOWNLOAD_ALL_VERSIONS "Download all versions for trailbook ${args_NAME} and build complete trailbook" OFF)
option(TRAILBOOK_${args_NAME}_IS_RELEASE "If enabled, the trailbook ${args_NAME} will be marked as release version in versions index" ON)
set(TRAILBOOK_${args_NAME}_INSTANCE_NAME "local" CACHE STRING "Instance name for trailbook ${args_NAME}")
option(TRAILBOOK_${args_NAME}_OVERWRITE_EXISTING_INSTANCE "Overwrite existing instance with name ${TRAILBOOK_${args_NAME}_INSTANCE_NAME} if it exists" OFF)
# Check that at least one of DOWNLOAD_ALL_VERSIONS or IS_RELEASE is ON
if(NOT TRAILBOOK_${args_NAME}_DOWNLOAD_ALL_VERSIONS AND NOT TRAILBOOK_${args_NAME}_IS_RELEASE)
message(FATAL_ERROR "add_trailbook: TRAILBOOK_${args_NAME}_DOWNLOAD_ALL_VERSIONS and TRAILBOOK_${args_NAME}_IS_RELEASE cannot both be OFF")
endif()
# Check that instance name is lowercase alphanumeric and underscores only
string(REGEX MATCH "^[a-z0-9_]+$" _valid_instance_name "${TRAILBOOK_${args_NAME}_INSTANCE_NAME}")
if("${_valid_instance_name}" STREQUAL "")
message(FATAL_ERROR "add_trailbook: TRAILBOOK_${args_NAME}_INSTANCE_NAME needs to be lowercase alphanumeric and underscores only")
endif()
# Parameter NAME
# is required
if("${args_NAME}" STREQUAL "")
message(FATAL_ERROR "add_trailbook: NAME argument is required")
endif()
# Parameter STEM_DIRECTORY
# - defaults to CMAKE_CURRENT_SOURCE_DIR
# - needs to be absolute path
if("${args_STEM_DIRECTORY}" STREQUAL "")
set(args_STEM_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
endif()
if(NOT IS_ABSOLUTE "${args_STEM_DIRECTORY}")
message(FATAL_ERROR "add_trailbook: STEM_DIRECTORY needs to be an absolute path")
endif()
cmake_path(SET args_STEM_DIRECTORY NORMALIZE ${args_STEM_DIRECTORY})
# Parameter REQUIREMENTS_TXT
# - defaults to ${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt if exists
# - needs to be absolute path if set
if("${args_REQUIREMENTS_TXT}" STREQUAL "")
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt")
set(args_REQUIREMENTS_TXT "${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt")
endif()
endif()
if(NOT "${args_REQUIREMENTS_TXT}" STREQUAL "")
if(NOT IS_ABSOLUTE "${args_REQUIREMENTS_TXT}")
message(FATAL_ERROR "add_trailbook: REQUIREMENTS_TXT needs to be an absolute path")
endif()
if(NOT EXISTS "${args_REQUIREMENTS_TXT}")
message(FATAL_ERROR "add_trailbook: REQUIREMENTS_TXT file does not exist: ${args_REQUIREMENTS_TXT}")
endif()
endif()
# Parameter DEPLOYED_DOCS_REPO_URL
# - required if TRAILBOOK_<NAME>_DOWNLOAD_ALL_VERSIONS is ON
if(TRAILBOOK_${args_NAME}_DOWNLOAD_ALL_VERSIONS AND "${args_DEPLOYED_DOCS_REPO_URL}" STREQUAL "")
message(FATAL_ERROR "add_trailbook: DEPLOYED_DOCS_REPO_URL argument is required if TRAILBOOK_${args_NAME}_DOWNLOAD_ALL_VERSIONS is ON")
endif()
# Parameter DEPLOYED_DOCS_REPO_BRANCH
# - defaults to 'main'
if("${args_DEPLOYED_DOCS_REPO_BRANCH}" STREQUAL "")
set(args_DEPLOYED_DOCS_REPO_BRANCH "main")
endif()
set(TRAILBOOK_INSTANCE_SOURCE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/trailbook_${args_NAME}_source")
set(TRAILBOOK_BUILD_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/trailbook_${args_NAME}_build")
set(TRAILBOOK_INSTANCE_BUILD_DIRECTORY "${TRAILBOOK_BUILD_DIRECTORY}/${TRAILBOOK_${args_NAME}_INSTANCE_NAME}")
set(TRAILBOOK_INSTANCE_IS_RELEASE "${TRAILBOOK_${args_NAME}_IS_RELEASE}")
set(TRAILBOOK_INSTANCE_DOWNLOAD_ALL_VERSIONS "${TRAILBOOK_${args_NAME}_DOWNLOAD_ALL_VERSIONS}")
message(STATUS "Adding trailbook: ${args_NAME}")
message(STATUS " Stem directory: ${args_STEM_DIRECTORY}")
message(STATUS " Build directory: ${TRAILBOOK_BUILD_DIRECTORY}")
message(STATUS " Instance source directory: ${TRAILBOOK_INSTANCE_SOURCE_DIRECTORY}")
message(STATUS " Instance build directory: ${TRAILBOOK_INSTANCE_BUILD_DIRECTORY}")
if(NOT "${args_REQUIREMENTS_TXT}" STREQUAL "")
message(STATUS " Requirements.txt: ${args_REQUIREMENTS_TXT}")
else()
message(STATUS " Requirements.txt: <none>")
endif()
message(STATUS " Deployed docs repo url: ${args_DEPLOYED_DOCS_REPO_URL}")
message(STATUS " Deployed docs repo branch: ${args_DEPLOYED_DOCS_REPO_BRANCH}")
_add_trailbook_check_requirements_txt()
add_custom_target(
trailbook_${args_NAME}_stage_prepare_sphinx_source_before
DEPENDS
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_PREPARE_SPHINX_SOURCE_BEFORE>
)
_add_trailbook_setup_build_directory()
_add_trailbook_copy_stem_command()
_add_trailbook_create_metadata_yaml_command()
set(DEPS_STAGE_PREPARE_SPHINX_SOURCE_AFTER
trailbook_${args_NAME}_stage_prepare_sphinx_source_before
${CHECK_DONE_FILE_SETUP_BUILD_DIRECTORY}
${STEM_FILES_BUILD_DIR}
${METADATA_YAML_FILE}
)
add_custom_target(
trailbook_${args_NAME}_stage_prepare_sphinx_source_after
DEPENDS
${DEPS_STAGE_PREPARE_SPHINX_SOURCE_AFTER}
COMMENT
"Prepare Sphinx source for trailbook: ${args_NAME}"
)
add_custom_target(
trailbook_${args_NAME}_stage_build_sphinx_before
DEPENDS
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_BUILD_SPHINX_BEFORE>
trailbook_${args_NAME}_stage_prepare_sphinx_source_after
)
_add_trailbook_sphinx_build_command()
set(DEPS_STAGE_BUILD_SPHINX_AFTER
trailbook_${args_NAME}_stage_build_sphinx_before
${CHECK_DONE_FILE_SPHINX_BUILD_COMMAND}
)
add_custom_target(
trailbook_${args_NAME}_stage_build_sphinx_after
DEPENDS
${DEPS_STAGE_BUILD_SPHINX_AFTER}
COMMENT
"Build Sphinx documentation for trailbook: ${args_NAME}"
)
add_custom_target(
trailbook_${args_NAME}_stage_postprocess_sphinx_before
DEPENDS
$<TARGET_PROPERTY:trailbook_${args_NAME},ADDITIONAL_DEPS_STAGE_POSTPROCESS_SPHINX_BEFORE>
trailbook_${args_NAME}_stage_build_sphinx_after
)
if(TRAILBOOK_INSTANCE_IS_RELEASE)
_add_trailbook_replace_latest_command()
_add_trailbook_copy_404_command()
_add_trailbook_render_redirect_template_command()
endif()
_add_trailbook_copy_versions_index_command()
set(DEPS_STAGE_POSTPROCESS_SPHINX_AFTER
trailbook_${args_NAME}_stage_postprocess_sphinx_before
${CHECK_DONE_FILE_REPLACE_LATEST}
${CHECK_DONE_FILE_COPY_404}
${CHECK_DONE_FILE_COPY_VERSIONS_INDEX}
${CHECK_DONE_FILE_RENDER_REDIRECT_TEMPLATE}
)
add_custom_target(
trailbook_${args_NAME}_stage_postprocess_sphinx_after
DEPENDS
${DEPS_STAGE_POSTPROCESS_SPHINX_AFTER}
COMMENT
"Post-process Sphinx documentation for trailbook: ${args_NAME}"
)
add_custom_target(
trailbook_${args_NAME} ALL
DEPENDS
trailbook_${args_NAME}_stage_postprocess_sphinx_after
COMMENT
"Build trailbook: ${args_NAME}"
)
_add_trailbook_preview_target()
_add_trailbook_live_preview_target()
set_target_properties(
trailbook_${args_NAME}
PROPERTIES
TRAILBOOK_INSTANCE_BUILD_DIRECTORY "${TRAILBOOK_INSTANCE_BUILD_DIRECTORY}"
TRAILBOOK_BUILD_DIRECTORY "${TRAILBOOK_BUILD_DIRECTORY}"
TRAILBOOK_INSTANCE_NAME "${TRAILBOOK_${args_NAME}_INSTANCE_NAME}"
TRAILBOOK_INSTANCE_SOURCE_DIRECTORY "${TRAILBOOK_INSTANCE_SOURCE_DIRECTORY}"
TRAILBOOK_CURRENT_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}"
ADDITIONAL_DEPS_STAGE_PREPARE_SPHINX_SOURCE_BEFORE ""
ADDITIONAL_DEPS_STAGE_BUILD_SPHINX_BEFORE ""
ADDITIONAL_DEPS_STAGE_POSTPROCESS_SPHINX_BEFORE ""
DEPS_STAGE_PREPARE_SPHINX_SOURCE_AFTER "${DEPS_STAGE_PREPARE_SPHINX_SOURCE_AFTER}"
DEPS_STAGE_BUILD_SPHINX_AFTER "${DEPS_STAGE_BUILD_SPHINX_AFTER}"
DEPS_STAGE_POSTPROCESS_SPHINX_AFTER "${DEPS_STAGE_POSTPROCESS_SPHINX_AFTER}"
)
endfunction()
Reference in New Issue View Git Blame Copy Permalink