docs: run the block sub script

docs/command.md

@@ -1,9 +1,13 @@
 ## Define a command
 
+<!-- {"file": "examples/add.py", "type": "example"} -->
 ```python
+"""Simple add program."""
+
 from typing_extensions import Annotated
 
-from clea import Integer, command
+from clea import Integer, command, run
+
 
 @command
 def add(
@@ -13,35 +17,30 @@ def add(
     """Add two numbers"""
 
     print(f"Total {n1 + n2}")
-```
 
-Invoke the command at runtime using
-
-```python
-from clea import run
 
 if __name__ == "__main__":
     run(cli=add)
 ```
 
-> The example is taken from [add.py](https://github.com/angrybayblade/clea/blob/main/examples/add.py) in the examples folder.
-
-You can check the command definition using 
+*The example is taken from [add.py](https://github.com/angrybayblade/clea/blob/main/examples/add.py) in the examples folder.*
 
+<!-- {"type": "exec", "directory": "examples/", "read": "stdout"} -->
 ```bash
 $ python add.py --help
 
 Usage: add [OPTIONS] N1 N2
 
-        Add two numbers
+	Add two numbers
 
 Options:
 
     --help                        Show help and exit.
 ```
 
-Execute the command using
+Running the application
 
+<!-- {"type": "exec", "directory": "examples/", "read": "stdout"} -->
 ```bash
 $ python add.py 2 3
 
@@ -50,32 +49,16 @@ Total 5
 
 ## With custom name
 
+<!-- {"file": "examples/add_numbers.py", "type": "example", "start": 7, "end": 15} -->
 ```python
-(...)
-
 @command(name="add-numbers")
 def add(
     n1: Annotated[int, Integer()],
     n2: Annotated[int, Integer()],
 ) -> None:
     """Add two numbers"""
-    print (f"Total: {n1+n2}")
-
-(...)
-```
-
-The custom name will show up as the command name
 
-```bash
-$ python add.py --help
-
-Usage: add-numbers [OPTIONS] N1 N2
-
-        Add two numbers
-
-Options:
-
-    --help                        Show help and exit.
+    print(f"Total {n1 + n2}")
 ```
 
 ## Next steps 

docs/context.md

@@ -4,8 +4,14 @@ Whenever a command is executed, a runtime object is created which holds state fo
 
 Context object provides a simple key-value data store for storing and retrieving data across the execution.
 
+<!-- {"file": "examples/context.py", "type": "example"} -->
 ```python
-from clea import Context, run, group
+"""Context example."""
+
+from clea.context import Context
+from clea.runner import run
+from clea.wrappers import group
+
 
 @group
 def admin(context: Context) -> None:
@@ -34,9 +40,14 @@ if __name__ == "__main__":
 
 You can define a custom context for tasks such as loading and storing application config.
 
+<!-- {"file": "examples/custom_context.py", "type": "example"} -->
 ```python
-from clea import run, command
-from clea import Context as BaseContext
+"""Custom context example."""
+
+from clea.context import Context as BaseContext
+from clea.runner import run
+from clea.wrappers import command
+
 
 class Context(BaseContext):
     """Custom context object"""

docs/group.md

@@ -1,12 +1,14 @@
 ## Define a group
 
-Define you first command group using 
-
+<!-- {"file": "examples/calculator.py", "type": "example"} -->
 ```python
-from clea import run, group, Integer, Boolean
+"""Calculator example."""
+
 
 from typing_extensions import Annotated
 
+from clea import Boolean, Integer, group, run
+
 
 @group
 def calculator() -> None:
@@ -23,64 +25,53 @@ def add(
     print(f"Answer {n1+n2}")
 
 
-if __name__ == "__main__":
-    run(cli=calculator)
-```
-
-> The example is taken from [calculator.py](https://github.com/angrybayblade/clea/blob/main/examples/calculator.py) in the examples folder.
-
-You can check the command definition using 
-
-```bash
-Usage: calculator [OPTIONS] 
-
-        CLI Calculator app.
-
-Options:
-
-    --help                        Show help and exit.
-
-Commands:
-
-    add                           Add two numbers.
-```
-
-Execute the command using
-
-```bash
-$ python calculator.py add 2 3
+@calculator.command
+def subtract(
+    n1: Annotated[int, Integer()],
+    n2: Annotated[int, Integer()],
+) -> None:
+    """Subtract two numbers."""
 
-Answer 5
-```
+    print(f"Answer {n1-n2}")
 
-## With custom name
 
-```python
-(...)
+@calculator.command
+def multiply(
+    n1: Annotated[int, Integer()],
+    n2: Annotated[int, Integer()],
+) -> None:
+    """Multiply two numbers."""
 
-@group(name="calculator-app")
-def calculator() -> None:
-    """CLI Calculator app."""
+    print(f"Answer {n1*n2}")
 
 
 @calculator.command
-def add(
+def devide(
     n1: Annotated[int, Integer()],
     n2: Annotated[int, Integer()],
+    round: Annotated[  # pylint: disable=redefined-builtin
+        bool, Boolean(help="Round up the answer")
+    ],
 ) -> None:
-    """Add two numbers."""
+    """Devide two numbers."""
 
-(...)
-```
+    if round:
+        print(f"Answer {n1//n2}")
+    else:
+        print(f"Answer {n1/n2}")
 
-The custom name will show up as the group name
 
+if __name__ == "__main__":
+    run(cli=calculator)
+```
+
+<!-- {"type": "exec", "directory": "examples/", "read": "stdout"} -->
 ```bash
 $ python calculator.py --help
 
-Usage: calculator-app [OPTIONS] 
+Usage: calculator [OPTIONS] 
 
-        CLI Calculator app.
+	CLI Calculator app.
 
 Options:
 
@@ -89,6 +80,18 @@ Options:
 Commands:
 
     add                           Add two numbers.
+    subtract                      Subtract two numbers.
+    multiply                      Multiply two numbers.
+    devide                        Devide two numbers.
+```
+
+Running the application
+
+<!-- {"type": "exec", "directory": "examples/", "read": "stdout"} -->
+```bash
+$ python calculator.py add 2 3
+
+Answer 5
 ```
 
 ## Next steps 

docs/index.md

@@ -1,6 +1,6 @@
 ## Introduction
 
-Clea is a light weight application framework for creating CLI applications in python. Clea is uses type annotations to generate the command/group defintions and parse the arguments at the runtime. To start with clea run
+Clea is a framework for creating CLI applications in python very quickly. Clea uses type annotations for defining arguments. To start with clea run
 
 ## Install
 
@@ -10,12 +10,16 @@ pip3 install clea
 
 ## Quickstart
 
-Define you first command using 
+Define your first application 
 
+<!-- {"file": "examples/add.py", "type": "example"} -->
 ```python
+"""Simple add program."""
+
 from typing_extensions import Annotated
 
-from clea import Integer, command
+from clea import Integer, command, run
+
 
 @command
 def add(
@@ -25,35 +29,15 @@ def add(
     """Add two numbers"""
 
     print(f"Total {n1 + n2}")
-```
 
-Invoke the command at runtime using
-
-```python
-from clea import run
 
 if __name__ == "__main__":
     run(cli=add)
 ```
 
-> The example is taken from [add.py](https://github.com/angrybayblade/clea/blob/main/examples/add.py) in the examples folder.
-
-You can check the command definition using 
-
-```bash
-$ python add.py --help
-
-Usage: add [OPTIONS] N1 N2
-
-        Add two numbers
-
-Options:
-
-    --help                        Show help and exit.
-```
-
 Execute the command using
 
+<!-- {"type": "exec", "directory": "examples/", "read": "stdout"} -->
 ```bash
 $ python add.py 2 3
 

docs/testing.md

@@ -2,9 +2,12 @@
 
 To test a clea application you can use the `isolated` flag in the `clea.runner.run` method. For example, to test the `add.py`
 
+<!-- {"file": "tests/test_examples/test_add.py", "type": "example"} -->
 ```python
+"""Test add.py"""
+
 from examples.add import add as cli
-from clea import run
+from clea.runner import run
 
 
 def test_missing_arguments() -> None:
@@ -22,4 +25,4 @@ def test_add() -> None:
     result = run(cli=cli, argv=["1", "2"], isolated=True)
     assert result.exit_code == 0
     assert "Total 3" in result.stdout
-```
+```