cariflex/tools/EVerest-main/cmake/trailbook/README.md

CMake Package trailbook

This package provides CMake functions and macros to include the build of a trailbook documentation in a CMake-based project.

Usage in CMake

To use this package in your CMake project, include the following line in your CMakeLists.txt file:

find_package(
    trailbook
    0.1.0
    REQUIRED
    PATHS "${CMAKE_SOURCE_DIR}/<path-to-the-package>"
)

• Specify the version to make sure you are using a compatible version of the package.
• If the package is not found, CMake will stop with an error due to the REQUIRED keyword.
• If the package is not installed in a standard location, you can specify the path to the package using the PATHS option.

After finding the package, you can use the provided functions. At the moment, the package provides the following functions:

add_trailbook()

This function is the initial call for your trailbook documentation. It can be called as follows:

add_trailbook(
    NAME <trailbook_name>
    [STEM_DIRECTORY <stem_directory>]
    [REQUIREMENTS_TXT <requirements_txt>]
    INSTANCE_NAME <instance_name>
    [DEPLOYED_DOCS_REPO_URL <deployed_docs_repo_url>]
    [DEPLOYED_DOCS_REPO_BRANCH <deployed_docs_repo_branch>]
)

• This function needs to be called once per trailbook.
• The NAME argument specifies the name of the trailbook. This name will be used to create unique target names.
• The optional STEM_DIRECTORY argument specifies the directory containing the Sphinx source files. If not provided, it defaults to ${CMAKE_CURRENT_SOURCE_DIR}
• The optional REQUIREMENTS_TXT argument specifies the path to a requirements.txt file for Python dependencies. If not provided, it defaults to ${STEM_DIRECTORY}/requirements.txt, if this file exists. This requirements file will be used to check if the required Python packages are installed and if not to install them, if a python virtual environment is active
• The INSTANCE_NAME argument specifies the name that is used for the version in the multiversion structure.
• The optional DEPLOYED_DOCS_REPO_URL argument specifies the URL of the repository where the already deployed documentation is located. It is required if TRAILBOOK_<NAME>_DOWNLOAD_ALL_VERSIONS is set to ON.
• The optional DEPLOYED_DOCS_REPO_BRANCH argument specifies the branch of the deployed documentation repository. It defaults to main if not provided.

Configuring

There are several options that can be configured for each trailbook by setting CMake variables.

TRAILBOOK_<NAME>_DOWNLOAD_ALL_VERSIONS

• <NAME> should be replaced with the trailbook name provided in the add_trailbook() function call.

If TRAILBOOK_<NAME>_DOWNLOAD_ALL_VERSIONS is set to ON, the build process will attempt to download all previously deployed versions of the trailbook from the specified repository. And then embed the new version into the multiversion structure.

If TRAILBOOK_<NAME>_DOWNLOAD_ALL_VERSIONS is set to OFF (default), only the current version of the trailbook will be built. For this an empty multiversion skeleton will be created.

This configuration shouldn'T be changed after the first build.

TRAILBOOK_<NAME>_IS_RELEASE

• <NAME> should be replaced with the trailbook name provided in the add_trailbook() function call.

If TRAILBOOK_<NAME>_IS_RELEASE is set to ON (default), the trailbook will be built as a release version. This means that the latest version is updated, and the index.html and 404.html files are updated.

If TRAILBOOK_<NAME>_IS_RELEASE is set to OFF, the mentioned files are not updated, and the latest version is not changed. This can be used for example to build nightly versions without affecting the released version.

Building

To build the trailbook documentation, simply run the following command, after configuring the project with CMake:

cmake --build <build_directory> --target trailbook_<trailbook_name>

• Replace <build_directory> with the path to your CMake build directory.
• Replace <trailbook_name> with the name of your trailbook provided in the add_trailbook() function call.

This target will trigger the full build of the trailbook documentation

Furthermore, you can use the following additional targets:

cmake --build <build_directory> --target trailbook_<trailbook_name>_preview

This target will start a local server to preview the built documentation.

cmake --build <build_directory> --target trailbook_<trailbook_name>_live_preview

This target will start a local server that watches for changes in the source files and automatically rebuilds the documentation and refreshes the preview in the browser.

How to build a extension for the trailbook package

The trailbook package provides a set of targets and target properties that can be used to hook into the build process of the trailbook documentation and extend it with custom functionality.

See the full explanation in the EXTENDING.md file.