Add an example for a CLI app also used as a Hera script (#1536)

**Pull Request Checklist**
- [x] Related to #1530
- [x] Tests added
- [x] Documentation/examples added
- [x] [Good commit messages](https://cbea.ms/git-commit/) and/or PR
title

**Description of PR**
Currently, a user may want to reuse a CLI app with Hera. `click` is a
popular choice but garbles the underlying function, rendering it
unusable with the `script` decorator (and not worth first-party support
at this time). Cappa, used for the `hera` CLI itself, does not interfere
with the function, so it is usable with the script decorator.

This PR adds a use-case/integration example for reusing a CLI app with
Hera. Also pointing out in a warning box that `click` will not
ordinarily work with the `script` decorator (requiring the `Script`
class).

cc @DanCardin sharing the cappa love 🫶

Signed-off-by: Elliot Gunton <[email protected]>
Co-authored-by: Sambhav Kothari <[email protected]>

Author: elliotgunton

docs/examples/workflows/use-cases/reusing_cli_app.md

@@ -0,0 +1,78 @@
+# Reusing Cli App
+
+
+
+This example shows how a CLI application built with [Cappa](https://github.com/DanCardin/cappa) can also be used as a `script` function.
+
+!!! Warning
+    Using the `script` decorator is not possible with other CLI libraries like [`click`](https://click.palletsprojects.com/en/stable/), and will require use of the `Script` class and setting `source=function_name`.
+    [See this issue discussion](https://github.com/argoproj-labs/hera/issues/1530#issuecomment-3616082722) for more details.
+
+
+=== "Hera"
+
+    ```python linenums="1"
+    import cappa
+
+    from hera.workflows import Workflow, script
+
+
+    @script()
+    def hello(count: int, name: str):
+        """Simple program that greets NAME for a total of COUNT times."""
+        for _ in range(count):
+            print(f"Hello {name}!")
+
+
+    with Workflow(
+        generate_name="cli-example-",
+        entrypoint="hello",
+        arguments={"count": 3, "name": "Hera"},
+    ) as w:
+        hello()
+
+
+    if __name__ == "__main__":
+        cappa.invoke(hello)
+    ```
+
+=== "YAML"
+
+    ```yaml linenums="1"
+    apiVersion: argoproj.io/v1alpha1
+    kind: Workflow
+    metadata:
+      generateName: cli-example-
+    spec:
+      entrypoint: hello
+      templates:
+      - name: hello
+        inputs:
+          parameters:
+          - name: count
+          - name: name
+        script:
+          image: python:3.10
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            import json
+            try: count = json.loads(r'''{{inputs.parameters.count}}''')
+            except: count = r'''{{inputs.parameters.count}}'''
+            try: name = json.loads(r'''{{inputs.parameters.name}}''')
+            except: name = r'''{{inputs.parameters.name}}'''
+
+            """Simple program that greets NAME for a total of COUNT times."""
+            for _ in range(count):
+                print(f'Hello {name}!')
+          command:
+          - python
+      arguments:
+        parameters:
+        - name: count
+          value: '3'
+        - name: name
+          value: Hera
+    ```
+

examples/workflows/use_cases/reusing-cli-app.yaml

@@ -0,0 +1,35 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Workflow
+metadata:
+  generateName: cli-example-
+spec:
+  entrypoint: hello
+  templates:
+  - name: hello
+    inputs:
+      parameters:
+      - name: count
+      - name: name
+    script:
+      image: python:3.10
+      source: |-
+        import os
+        import sys
+        sys.path.append(os.getcwd())
+        import json
+        try: count = json.loads(r'''{{inputs.parameters.count}}''')
+        except: count = r'''{{inputs.parameters.count}}'''
+        try: name = json.loads(r'''{{inputs.parameters.name}}''')
+        except: name = r'''{{inputs.parameters.name}}'''
+
+        """Simple program that greets NAME for a total of COUNT times."""
+        for _ in range(count):
+            print(f'Hello {name}!')
+      command:
+      - python
+  arguments:
+    parameters:
+    - name: count
+      value: '3'
+    - name: name
+      value: Hera

examples/workflows/use_cases/reusing_cli_app.py

@@ -0,0 +1,29 @@
+"""This example shows how a CLI application built with [Cappa](https://github.com/DanCardin/cappa) can also be used as a `script` function.
+
+!!! Warning
+    Using the `script` decorator is not possible with other CLI libraries like [`click`](https://click.palletsprojects.com/en/stable/), and will require use of the `Script` class and setting `source=function_name`.
+    [See this issue discussion](https://github.com/argoproj-labs/hera/issues/1530#issuecomment-3616082722) for more details.
+"""
+
+import cappa
+
+from hera.workflows import Workflow, script
+
+
+@script()
+def hello(count: int, name: str):
+    """Simple program that greets NAME for a total of COUNT times."""
+    for _ in range(count):
+        print(f"Hello {name}!")
+
+
+with Workflow(
+    generate_name="cli-example-",
+    entrypoint="hello",
+    arguments={"count": 3, "name": "Hera"},
+) as w:
+    hello()
+
+
+if __name__ == "__main__":
+    cappa.invoke(hello)

tests/submissions/test_examples.py

@@ -22,6 +22,7 @@
     "new_decorators_auto_template_refs",  # Uses TemplateRefs to non-existent WorkflowTemplates
     "template_refs",  # Also uses TemplateRefs - the WorkflowTemplates are in the file though
     "parquet_pandas",
+    "reusing_cli_app",
 }
 SKIP_SUBMISSION_EXAMPLES = SKIP_LINT_EXAMPLES.union(
     {