Merge pull request #20 from angrybayblade/fix/docs

Documentation cleanup

.github/workflows/release.yml

@@ -33,8 +33,8 @@ jobs:
           password: ${{ secrets.PYPI_API_TOKEN }}
           skip-existing: true
           packages-dir: dist/
-      - name: Deploy Docs
-        run:  |
-          pip install --user --upgrade setuptools
-          pip install tox==4.6.3
-          tox -e docs-deploy
+      # - name: Deploy Docs
+      #   run:  |
+      #     pip install --user --upgrade setuptools
+      #     pip install tox==4.6.3
+      #     tox -e docs-deploy

.github/workflows/workflow.yml

@@ -63,6 +63,8 @@ jobs:
         run: tox -e mypy
       - name: Pylint
         run: tox -e pylint
+      - name: Documentation checks
+        run: tox -e docs-block-check
 
   test:
     continue-on-error: True

clea/__init__.py

@@ -3,6 +3,7 @@
 """
 
 from .context import Context  # noqa: F401
+from .exceptions import CleaException  # noqa: F401
 from .params import (  # noqa: F401
     Boolean,
     Choice,

clea/params.py

@@ -109,9 +109,14 @@ def help(self) -> str:
         """Help string."""
         if self.short_flag is not None:
             help_string = f"{self.short_flag}, "
+            if self.long_flag is not None:
+                help_string += f"{self.long_flag}, "
+            help_string = help_string[:-2]
         else:  # pragma: nocover
             help_string = ""
-        help_string += f"{self.long_flag}"
+            if self.long_flag is not None:
+                help_string += f"{self.long_flag}"
+
         if self._help is not None:
             help_string += " " * (HELP_COL_LENGTH - len(help_string))
             help_string += self._help
@@ -182,12 +187,16 @@ def parse(self, value: t.Any) -> t.List[str]:
         return self.container
 
     def help(self) -> str:
-        """Help string."""
         if self.short_flag is not None:
             help_string = f"{self.short_flag}, "
-        else:
-            help_string = ""  # pragma: nocover
-        help_string += f"{self.long_flag}"
+            if self.long_flag is not None:
+                help_string += f"{self.long_flag}, "
+            help_string = help_string[:-2]
+        else:  # pragma: nocover
+            help_string = ""
+            if self.long_flag is not None:
+                help_string += f"{self.long_flag}"
+
         if self._help is not None:
             help_string += " " * (HELP_COL_LENGTH - len(help_string))
             help_string += self._help
@@ -230,9 +239,14 @@ def help(self) -> str:
         """Help string."""
         if self.short_flag is not None:
             help_string = f"{self.short_flag}, "
-        else:
-            help_string = ""  # pragma: nocover
-        help_string += f"{self.long_flag}"
+            if self.long_flag is not None:
+                help_string += f"{self.long_flag}, "
+            help_string = help_string[:-2]
+        else:  # pragma: nocover
+            help_string = ""
+            if self.long_flag is not None:
+                help_string += f"{self.long_flag}"
+
         choices = "|".join(list(map(lambda x: x.value, self.enum)))
         help_string += f"  [{choices}]"
         if self._help is not None:

docs/command.md

@@ -1,10 +1,13 @@
 ## Define a command
 
+<!-- {"file": "examples/add.py", "type": "example"} -->
 ```python
+"""Simple add program."""
+
 from typing_extensions import Annotated
 
-from clea.params import Integer
-from clea.wrappers import command
+from clea import Integer, command, run
+
 
 @command
 def add(
@@ -14,35 +17,30 @@ def add(
     """Add two numbers"""
 
     print(f"Total {n1 + n2}")
-```
 
-Invoke the command at runtime using
-
-```python
-from clea.runner 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
 
@@ -51,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,7 +4,10 @@ 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
+"""Context example."""
+
 from clea.context import Context
 from clea.runner import run
 from clea.wrappers import group
@@ -37,7 +40,10 @@ 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
+"""Custom context example."""
+
 from clea.context import Context as BaseContext
 from clea.runner import run
 from clea.wrappers import command

docs/group.md

@@ -1,14 +1,14 @@
 ## Define a group
 
-Define you first command group using 
-
+<!-- {"file": "examples/calculator.py", "type": "example"} -->
 ```python
-from clea.runner import run
-from clea.wrappers import group
-from clea.params import Integer, Boolean
+"""Calculator example."""
+
 
 from typing_extensions import Annotated
 
+from clea import Boolean, Integer, group, run
+
 
 @group
 def calculator() -> None:
@@ -25,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:
 
@@ -91,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