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
137
tools/EVerest-main/cmake/trailbook/README.md
Normal file
137
tools/EVerest-main/cmake/trailbook/README.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user