added full documentation of the rule module

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 * Added full API documentation of the `gcip.core.need` module.
+* Added full API documentation of the `gcip.core.rule` module.
+* Added API documentation to the `gcip.core.service` module.
 
 ## [0.7.0] - 2021-04-19
 

gcip/core/rule.py

@@ -1,3 +1,17 @@
+"""This module represents the Gitlab CI [rules](https://docs.gitlab.com/ee/ci/yaml/#rules) keyword.
+
+Use rules to include or exclude jobs in pipelines.
+
+```
+my_job.prepend_rules(
+    Rule(
+        if_statement='$CI_COMMIT_BRANCH == "master"',
+        when=WhenStatement.ON_FAILURE,
+        allow_failure: True,
+        )
+    )
+```
+"""
 from __future__ import annotations
 
 from enum import Enum
@@ -13,6 +27,8 @@
 
 
 class WhenStatement(Enum):
+    """This enum holds different [when](https://docs.gitlab.com/ee/ci/yaml/#when) statements for `Rule`s."""
+
     ALWAYS = "always"
     DELAYED = "delayed"
     MANUAL = "manual"
@@ -22,6 +38,19 @@ class WhenStatement(Enum):
 
 
 class Rule:
+    """This module represents the Gitlab CI [rules](https://docs.gitlab.com/ee/ci/yaml/#rules) keyword.
+
+    Use `rules` to include or exclude jobs in pipelines.
+
+    Args:
+        if_statement (Optional[str], optional): The [rules:if clause](https://docs.gitlab.com/ee/ci/yaml/#when) which decides when
+            a job to the pipeline. Defaults to None.
+        when (WhenStatement, optional): The [when](https://docs.gitlab.com/ee/ci/yaml/#when) attribute which decides when to run a job.
+            Defaults to WhenStatement.ON_SUCCESS.
+        allow_failure (bool, optional): The [allow_failure](https://docs.gitlab.com/ee/ci/yaml/#allow_failure) attribute which let a
+            job fail without impacting the rest of the CI suite. Defaults to False.
+    """
+
     def __init__(
         self,
         *args: Any,
@@ -34,10 +63,47 @@ def __init__(
         self._allow_failure = allow_failure
 
     def never(self) -> Rule:
+        """
+        This method returns a copy of this rule with the `when` attribute set to `WhenStatement.NEVER`.
+
+        This method is intended to be used for predefined rules. For instance you have defined an
+        often used rule `on_master` whose if statement checks if the pipeline is executed on branch
+        `master`. Then you can either run a job, if on master...
+
+        ```
+        my_job.append_rules(on_master)
+        ```
+
+        ... or do not run a job if on master...
+
+        ```
+        my_job.append_rules(on_master.never())
+        ```
+
+        Returns:
+            Rule: A new rule object with `when` set to `WhenStatement.NEVER`.
+        """
         self._when = WhenStatement.NEVER
         return self
 
+    def copy(self) -> Rule:
+        """
+        Returns an identical copy of that rule.
+
+        Returns:
+            Rule: A new rule object with identical configuration.
+        """
+        return Rule(self._if, self._when, self._allow_failure)
+
     def render(self) -> Dict[str, Union[str, bool]]:
+        """Return a representation of this Rule object as dictionary with static values.
+
+        The rendered representation is used by the gcip to dump it
+        in YAML format as part of the .gitlab-ci.yml pipeline.
+
+        Returns:
+            Dict[str, Any]: A dictionary representing the rule object in Gitlab CI.
+        """
         rendered_rule: Dict[str, Union[str, bool]] = {}
         if self._if:
             rendered_rule.update({"if": self._if})

gcip/core/service.py

@@ -1,8 +1,29 @@
+"""**ALPHA** This module represents the Gitlab CI [Service](https://docs.gitlab.com/ee/ci/yaml/README.html#services) keyword.
+
+The services keyword defines a Docker image that runs during a job linked to the Docker image that the image keyword defines.
+This allows you to access the service image during build time.
+
+Currently this module is an unfinished prototype.
+"""
+
+
 class Service:
-    """This class represents the Gitlab CI [Service](https://docs.gitlab.com/ee/ci/yaml/README.html#services) keyword."""
+    """**ALPHA** This class represents the Gitlab CI [Service](https://docs.gitlab.com/ee/ci/yaml/README.html#services) keyword.
+
+    Currently there is nothing more implemented than providing a service name. In general the `service` functionality
+    currently isn't well implemented, as it is only available for `gcip.core.pipeline.Pipeline`s.
+    """
 
     def __init__(self, name: str):
         self._name = name
 
     def render(self) -> str:
+        """Return a representation of this Service object as dictionary with static values.
+
+        The rendered representation is used by the gcip to dump it
+        in YAML format as part of the .gitlab-ci.yml pipeline.
+
+        Returns:
+            Dict[str, Any]: A dictionary representing the service object in Gitlab CI.
+        """
         return self._name