Add documentation

README.md

@@ -76,6 +76,11 @@ models
 > [!WARNING]
 > It is possible, but strongly discouraged, to specify the location of a `yarpConfigurationFile` using absolute paths or paths relative to the current working directory: the former approach is not portable, while the latter only works if the library is loaded from the directory it was intended to be loaded from.
 
+## Tools
+
+This repository also contain some helper executable tools:
+* [`gz-sim-yarp-plugins-check-model`](./tools/gz-sim-yarp-plugins-check-model/README.md): Tool to automatically check if a world or a model that uses gz-sim-yarp-plugins is able to load correctly.
+
 ## Run Tests
 
 To run the tests, just configure the project with the `BUILD_TESTING` option, and run `ctest`:

docs/build-from-source.md

@@ -25,7 +25,7 @@ in addition to the usual dependencies used to configure, compile and test C++ pa
 If you are using conda (or mamba), the dependencies of `gz-sim-yarp-plugins` can be installed with:
 
 ```bash
-conda install -c conda-forge libgz-sim8 yarp ycm-cmake-modules cmake ninja pkg-config cmake compilers gtest
+conda install -c conda-forge libgz-sim8 yarp ycm-cmake-modules cmake ninja pkg-config cmake compilers gtest cli11
 ```
 
 This command should be executed in a terminal with the environment activated.
@@ -115,3 +115,10 @@ export GZ_SIM_SYSTEM_PLUGIN_PATH=${GZ_SIM_SYSTEM_PLUGIN_PATH}:<install_location>
 ~~~
 
 where `<install_location>` is the directory passed to `CMAKE_INSTALL_PREFIX` during the CMake configuration.
+
+To ensure that the tools are found, instead you need to add their location to the `PATH`:
+
+~~~
+export PATH=${PATH}:<install_location>/bin
+~~~
+

tools/gz-sim-yarp-plugins-check-model/README.md

@@ -0,0 +1,37 @@
+# gz-sim-yarp-plugins-check-model
+
+The `gz-sim-yarp-plugins-check-model` is an helper tool that can be used to check automatically if a world or a model containing `gz-sim-yarp-plugins` is able to start correctly, and if all the `gz-sim-yarp-plugins` in it load correctly. It can be useful to automatically check in Continuous Integration if some model or world contained in a given repo (and all its associated configuration file) are able to load.
+
+If you want to check if a world is able to load correctly, you can run the tool as:
+
+~~~
+gz-sim-yarp-plugins-check-model --world-file ./local/to/world.sdf
+~~~
+
+while to check if a model is able to load correctly, you can pass:
+
+~~~
+gz-sim-yarp-plugins-check-model --model-uri model://ergoCubGazeboV1
+~~~
+
+The tool will return 0 as exit value if the world or model loaded correctly, or 1 if there was an error in the loading.
+
+For more information and options, run `gz-sim-yarp-plugins-check-model --help`.
+
+
+## Usage in CI
+
+To run the tool in CI, you can just invoke it in your CI script with the file or model you want to check as:
+
+~~~
+gz-sim-yarp-plugins-check-model --model-uri model://ergoCubGazeboV1
+~~~
+
+Remember that environment variables such as  `GZ_SIM_RESOURCE_PATH` used to find `model://` files need to be set for the tool to work appropriately.
+
+You can also use the tool as part of a CMake test, with the following CMake code:
+
+~~~cmake
+add_test(NAME project-check-world-loads-correctly
+         COMMAND gz-sim-yarp-plugins-check-model --world-file ${PROJECT_SOURCE_DIR}/location/of/world/file.sdf)
+~~~