From 86bea780e0623f88a062f43e7fdffcd6d7057da5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Ricks?= <bjoern.ricks@greenbone.net>
Date: Mon, 5 Feb 2024 15:46:36 +0100
Subject: [PATCH] Add: Improve documentation of pontos.github.actions

Include ActionOutput to public API and therefore include it in the docs
too. Add more docstrings and examples.
---
 pontos/github/actions/__init__.py |  3 ++-
 pontos/github/actions/core.py     | 45 +++++++++++++++++++++++++++++--
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/pontos/github/actions/__init__.py b/pontos/github/actions/__init__.py
index 16f5fb22..bed9939c 100644
--- a/pontos/github/actions/__init__.py
+++ b/pontos/github/actions/__init__.py
@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 #
 
-from .core import ActionIO, Console
+from .core import ActionIO, ActionOutput, Console
 from .env import GitHubEnvironment
 from .errors import GitHubActionsError
 from .event import (
@@ -18,6 +18,7 @@
 __all__ = (
     "GitHubActionsError",
     "ActionIO",
+    "ActionOutput",
     "Console",
     "GitHubEnvironment",
     "GitHubEvent",
diff --git a/pontos/github/actions/core.py b/pontos/github/actions/core.py
index 81947b77..337b7bdb 100644
--- a/pontos/github/actions/core.py
+++ b/pontos/github/actions/core.py
@@ -9,9 +9,10 @@
 from pathlib import Path
 from typing import Generator, Optional
 
-from pontos.github.actions.errors import GitHubActionsError
 from pontos.typing import SupportsStr
 
+from .errors import GitHubActionsError
+
 
 def _to_options(
     name: Optional[str] = None,
@@ -55,6 +56,7 @@ def _message(
 class Console:
     """
     Class for printing messages to the action console
+
     """
 
     @classmethod
@@ -63,6 +65,14 @@ def group(cls, title: str):
         """
         ContextManager to display a foldable group
 
+        .. code-block:: python
+
+            from pontos.github.actions import Console
+
+            console = Console()
+            with console.group("my-group"):
+                console.log("some message)
+
         Args:
             title: Title of the group
         """
@@ -190,6 +200,10 @@ def debug(message: str):
 
 
 class ActionOutput:
+    """
+    A GitHub Action output
+    """
+
     def __init__(self, file: TextIOWrapper) -> None:
         self._file = file
 
@@ -207,6 +221,10 @@ def write(self, name: str, value: SupportsStr):
 
 
 class ActionIO:
+    """
+    Class with static methods for handling GitHub Action IO
+    """
+
     @staticmethod
     def has_output() -> bool:
         """
@@ -218,9 +236,18 @@ def has_output() -> bool:
     @contextmanager
     def out() -> Generator[ActionOutput, None, None]:
         """
-        Create action output
+        Create an action output to write several output values
 
         An action output can be consumed by another job
+
+        Example:
+            .. code-block:: python
+
+                from pontos.github.actions import ActionIO
+
+                with ActionIO.out() as out:
+                    out.write("foo", "bar")
+                    out.write("lorem", "ipsum")
         """
         output_filename = os.environ.get("GITHUB_OUTPUT")
         if not output_filename:
@@ -239,6 +266,13 @@ def output(name: str, value: SupportsStr):
 
         An action output can be consumed by another job
 
+        Example:
+            .. code-block:: python
+
+                from pontos.github.actions import ActionIO
+
+                ActionIO.output("foo", "bar")
+
         Args:
             name: Name of the output variable
             value: Value of the output variable
@@ -258,6 +292,13 @@ def input(name: str, default: Optional[str] = None) -> Optional[str]:
         """
         Get the value of an action input
 
+        Example:
+            .. code-block:: python
+
+                from pontos.github.actions import ActionIO
+
+                value = ActionIO.input("foo", "bar")
+
         Args:
             name: Name of the input variable
             default: Use as default if the is no value for the variable