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
This commit is contained in:
Eric F
721
tools/EVerest-main/cmake/trailbook/add-trailbook.cmake
Normal file
721
tools/EVerest-main/cmake/trailbook/add-trailbook.cmake
Normal file
@@ -0,0 +1,721 @@
|
||||
|
||||
# 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
Block a user