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
88 lines
3.3 KiB
Markdown
88 lines
3.3 KiB
Markdown
# trailbook: EVerest
|
|
|
|
The EVerest documentation uses the CMake package `trailbook`
|
|
to build and manage its documentation.
|
|
Additional it uses the extension package `trailbook-ext-everest`
|
|
|
|
## Configure CMake
|
|
|
|
There are three CMake variables you need to know about.
|
|
|
|
### `EVEREST_BUILD_DOCS`
|
|
|
|
The CMake variable `EVEREST_BUILD_DOCS` enables or disables the building of the
|
|
EVerest documentation. It is disabled by default. To enable it, set the variable to `ON` when configuring CMake:
|
|
|
|
```bash
|
|
cmake -D EVEREST_BUILD_DOCS=ON <path_to_source>
|
|
```
|
|
|
|
### `TRAILBOOK_everest_DOWNLOAD_ALL_VERSIONS`
|
|
|
|
The CMake variable `TRAILBOOK_everest_DOWNLOAD_ALL_VERSIONS` controls whether
|
|
all available versions of the EVerest documentation are downloaded during the build process.
|
|
By default, this variable is set to `OFF`, meaning an empty multiversion skeleton is created
|
|
during the build.
|
|
|
|
To enable the downloading of all available versions, set the variable to `ON` when configuring CMake:
|
|
|
|
```bash
|
|
cmake -D EVEREST_BUILD_DOCS=ON -D TRAILBOOK_everest_DOWNLOAD_ALL_VERSIONS=ON <path_to_source>
|
|
```
|
|
|
|
With this the `everest.github.io` repository cloned and the new built documentation is embedded into
|
|
the exisiting multiversion structure.
|
|
|
|
### `TRAILBOOK_everest_IS_RELEASE`
|
|
|
|
If you don't want to deploy the documentation you probably don't need to care about this variable.
|
|
|
|
The CMake variable `TRAILBOOK_everest_IS_RELEASE` indicates whether the current build is a release build. It defaults to `ON` which means that files in the root of the multiversion structure
|
|
as `index.html` and `404.html` become updated. Additionally the `latest` symlink is updated to point to the current version.
|
|
|
|
In case of the need to build the documentation as nightly for example the variable can
|
|
be set to `OFF` when configuring CMake:
|
|
|
|
```bash
|
|
cmake -D EVEREST_BUILD_DOCS=ON -D TRAILBOOK_everest_DOWNLOAD_ALL_VERSIONS=ON -D TRAILBOOK_everest_IS_RELEASE=OFF <path_to_source>
|
|
```
|
|
|
|
**Note:** Building the documentation required `EDM` to be installed on the host system.
|
|
|
|
## Build
|
|
|
|
There are three targets available to work with the EVerest documentation:
|
|
|
|
```bash
|
|
cmake --build <build_directory> --target trailbook_everest
|
|
```
|
|
Builds the EVerest documentation.
|
|
|
|
```bash
|
|
cmake --build <build_directory> --target trailbook_everest_preview
|
|
```
|
|
Builds the EVerest documentation and serves it with a local web server
|
|
for previewing.
|
|
|
|
```bash
|
|
cmake --build <build_directory> --target trailbook_everest_live_preview
|
|
```
|
|
Builds the EVerest documentation and serves it with a local web server
|
|
for previewing. Additionally it watches for changes in the source files
|
|
and automatically rebuilds the documentation and refreshes the preview
|
|
in the browser.
|
|
|
|
## How things work
|
|
|
|
The trailbook is initialized in `${CMAKE_SOURCE_DIR}/docs/CMakeLists.txt`
|
|
with the `add_trailbook()` function call.
|
|
|
|
At the same file an edm snapshot yaml file is added to the documentation by
|
|
calling the function `trailbook_ev_create_snapshot()`.
|
|
|
|
Module explanations, modules references, type references and interface references are added automatically in `${CMAKE_SOURCE_DIR}/cmake/everest-generate.cmake`, by calling the functions
|
|
* `trailbook_ev_generate_rst_from_manifest()`,
|
|
* `trailbook_ev_generate_rst_from_types()`,
|
|
* `trailbook_ev_generate_rst_from_interface()`, and
|
|
* `trailbook_ev_add_module_explanation()`.
|