Add examples to ExecuteProcess docs (#525)

Signed-off-by: Ivan Santiago Paunovic <[email protected]>

Author: ivanpauno

launch/launch/actions/conftest.py

@@ -15,6 +15,8 @@
 # imports needed for doctests
 import launch
 import launch.actions
+import launch.conditions
+import launch.substitutions
 
 import pytest
 
@@ -23,5 +25,10 @@
 def add_imports_to_doctest_namespace(doctest_namespace):
     doctest_namespace['launch'] = launch
     doctest_namespace['LaunchDescription'] = launch.LaunchDescription
-    for x in launch.actions.__all__:
-        doctest_namespace[x] = getattr(launch.actions, x)
+    for subpackage in (
+        launch.actions,
+        launch.conditions,
+        launch.substitutions,
+    ):
+        for x in subpackage.__all__:
+            doctest_namespace[x] = getattr(subpackage, x)

launch/launch/actions/execute_process.py

@@ -84,7 +84,93 @@
 
 @expose_action('executable')
 class ExecuteProcess(Action):
-    """Action that begins executing a process and sets up event handlers for the process."""
+    """
+    Action that begins executing a process and sets up event handlers for it.
+
+    Simple example:
+
+        .. doctest::
+
+            >>> ld = LaunchDescription([
+            ...     ExecuteProcess(
+            ...         cmd=['ls', '-las'],
+            ...         name='my_ls_process',  # this is optional
+            ...         output='both',
+            ...     ),
+            ... ])
+
+        .. code-block:: xml
+
+            <launch>
+                <executable cmd="ls -las" name="my_ls_process" output="both"/>
+            </launch>
+
+    Substitutions in the command:
+
+        .. doctest::
+
+            >>> ld = LaunchDescription([
+            ...     DeclareLaunchArgument(name='file_path', description='file path to cat'),
+            ...     ExecuteProcess(
+            ...         # each item of the command arguments' list can be:
+            ...         # a string ('cat'),
+            ...         # a substitution (`LaunchConfiguration('file_path')`),
+            ...         # or a list of string/substitutions
+            ...         # (`[LaunchConfiguration('directory'), '/file.txt']`)
+            ...         cmd=['cat', LaunchConfiguration('file_path')],
+            ...     ),
+            ... ])
+
+        .. code-block:: xml
+
+            <launch>
+                <arg name="file_path" description="path of the file to cat"/>
+                <executable cmd="cat $(var file_path)"/>
+            </launch>
+
+    Optional cli argument:
+
+        .. doctest::
+
+            >>> ld = LaunchDescription([
+            ...     DeclareLaunchArgument(name='open_gui', default_value='False'),
+            ...     ExecuteProcess(
+            ...         cmd=['my_cmd', '--open-gui'],
+            ...         condition=IfCondition(LaunchConfiguration('open_gui')),
+            ...     ),
+            ...     ExecuteProcess(
+            ...         cmd=['my_cmd'],
+            ...         condition=UnlessCondition(LaunchConfiguration('open_gui')),
+            ...     ),
+            ... ])
+
+        .. code-block:: xml
+
+            <launch>
+                <arg name="open_gui" description="when truthy, the gui will be opened"/>
+                <executable cmd="my_cmd --open-gui" if="$(var open_gui)"/>
+                <executable cmd="my_cmd" unless="$(var open_gui)"/>
+            </launch>
+
+    Environment variables:
+
+        .. doctest::
+
+            >>> ld = LaunchDescription([
+            ...     ExecuteProcess(
+            ...         cmd=['my_cmd'],
+            ...         additional_env={'env_variable': 'env_var_value'},
+            ...     ),
+            ... ])
+
+        .. code-block:: xml
+
+            <launch>
+                <executable cmd="my_cmd">
+                    <env name="env_variable" value="env_var_value"/>
+                </executable>
+            </launch>
+    """
 
     def __init__(
         self,