d398a6ced2
- 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
138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```cmake
|
|
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:
|
|
|
|
```cmake
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cmake --build <build_directory> --target trailbook_<trailbook_name>_preview
|
|
```
|
|
|
|
This target will start a local server to preview the built documentation.
|
|
|
|
```bash
|
|
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](EXTENDING.md) file.
|