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
3.3 KiB
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:
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:
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:
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:
cmake --build <build_directory> --target trailbook_everest
Builds the EVerest documentation.
cmake --build <build_directory> --target trailbook_everest_preview
Builds the EVerest documentation and serves it with a local web server for previewing.
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(), andtrailbook_ev_add_module_explanation().