Clarify custom template usage (#552)

Signed-off-by: JLBuenoLopez-eProsima <joseluisbueno@eprosima.com>
eProsima · Sep 11, 2023 · 83d288d · 83d288d
1 parent ccb4d10
commit 83d288d
Showing 1 changed file with 51 additions and 35 deletions.
diff --git a/docs/fastddsgen/usage/usage.rst b/docs/fastddsgen/usage/usage.rst
@@ -47,40 +47,56 @@ The expected argument list of the application is:
 
 Where the option choices are:
 
-+---------------------+------------------------------------------------------------------------------------------------+
-| Option              | Description                                                                                    |
-+=====================+================================================================================================+
-| -help               | Shows the help information.                                                                    |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -version            | Shows the current version of eProsima *Fast DDS-Gen*.                                          |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -d <directory>      | Sets the output directory where the generated files are created.                               |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -I <directory>      | Add directory to preprocessor include paths.                                                   |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -t <directory>      | Sets a specific directory as a temporary directory.                                            |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -example <platform> | Generates an example and a solution to compile the generated source code for a specific |br|   |
-|                     | platform. The help command shows the supported platforms.                                      |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -replace            | Replaces the generated source code files even if they exist.                                   |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -ppDisable          | Disables the preprocessor.                                                                     |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -ppPath             | Specifies the preprocessor path.                                                               |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -extrastg <template>| Specifies a custom template. Template location must be in classpath.                           |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -typeobject         | Generates `TypeObject` files for the IDL provided and modifies MyType constructor to |br|      |
-|                     | register the TypeObject representation into the factory.                                       |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -typeros2           | Generates type naming compatible with ROS 2                                                    |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -python             | Generates source code and a CMake solution to compile a library containing the data types |br| |
-|                     | Python bindings required to run a *Fast DDS* Python-based application. This option is    |br|  |
-|                     | incompatible with the `-example` and `-typeobject` ones.                                       |
-+---------------------+------------------------------------------------------------------------------------------------+
-| -cs                 | Enables Case Sensitivity                                                                       |
-+---------------------+------------------------------------------------------------------------------------------------+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - Option
+     - Description
+   * - -help
+     - Shows the help information
+   * - -version
+     - Shows the current version of eProsima *Fast DDS-Gen*.
+   * - -d <directory>
+     - Sets the output directory where the generated files are created.
+   * - -I <directory>
+     - Add directory to preprocessor include paths.
+   * - -t <directory>
+     - Sets a specific directory as a temporary directory.
+   * - -example <platform>
+     - Generates an example and a solution to compile the generated source code for a specific |br|
+       platform.
+       The help command shows the supported platforms.
+   * - -replace
+     - Replaces the generated source code files even if they exist.
+   * - -ppDisable
+     - Disables the preprocessor.
+   * - -ppPath
+     - Specifies the preprocessor path.
+   * - -extrastg <template> <output>
+     - Specifies a custom template.
+       Template location must be in classpath.
+   * - -typeobject
+     - Generates `TypeObject` files for the IDL provided and modifies MyType constructor to |br|
+       register the TypeObject representation into the factory.
+   * - -typeros2
+     - Generates type naming compatible with ROS 2
+   * - -python
+     - Generates source code and a CMake solution to compile a library containing the data types |br|
+       Python bindings required to run a *Fast DDS* Python-based application.
+       This option is |br|
+       incompatible with the `-example` and `-typeobject` ones.
+   * - -cs
+     - Enables Case Sensitivity
 
 Please refer to :ref:`dynamic-types` for more information on TypeObject representation.
+
+.. note::
+
+    In order to use custom templates, it is recommended to use the following command:
+
+    .. code-block:: bash
+
+        java -cp <template_path>;<path to fastddsgen.jar> com.eprosima.fastdds.fastddsgen -extrastg <template> <output> <idl file>
+
+    If the ``jar`` file is directly used, the manifest overrides the classpath set by the user.