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,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",

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