Refactoring/13 documentation and formatting (#30)

Release notes

* method documentation
* module documentation
* class documentation
* implementing Black format tool
* Black tool check into CI
* all python code formatted
* README.md updated with using new tools

.github/workflows/static_analysis_and_tests.yml

@@ -38,9 +38,31 @@ jobs:
             echo "Success: Pylint score is above 9.5 (project score: $PYLINT_SCORE)."
           fi
 
+  code-format-check:
+    runs-on: ubuntu-latest
+    name: Black Format Check
+    steps:
+      - name: Checkout repository
+        uses: actions/[email protected]
+
+      - name: Set up Python
+        uses: actions/[email protected]
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+
+      - name: Check code format with Black
+        id: check-format
+        run: |
+          black --check $(git ls-files '*.py')
+
   python-tests:
     runs-on: ubuntu-latest
-    name: Python tests
+    name: Python Tests
     steps:
       - name: Checkout repository
         uses: actions/[email protected]

.pylintrc

@@ -179,7 +179,7 @@ const-naming-style=UPPER_CASE
 
 # Minimum line length for functions/classes that require docstrings, shorter
 # ones are exempt.
-docstring-min-length=-1
+docstring-min-length=5
 
 # Naming style matching correct function names.
 function-naming-style=snake_case
@@ -426,11 +426,7 @@ confidence=HIGH,
 # --enable=similarities". If you want to run only the classes checker, but have
 # no Warning level messages displayed, use "--disable=all --enable=classes
 # --disable=W".
-# TODO: Remove after this PR
-disable=C0116,
-        C0115,
-        C0114,
-        raw-checker-failed,
+disable=raw-checker-failed,
         bad-inline-option,
         locally-disabled,
         file-ignored,

README.md

@@ -15,6 +15,7 @@
 - [Project Setup](#project-setup)
 - [Run Scripts Locally](#run-scripts-locally)
 - [Run Pylint Check Locally](#run-pylint-check-locally)
+- [Run Black Tool Locally](#run-black-tool-locally)
 - [Run unit test](#run-unit-test)
 - [Deployment](#deployment)
 - [Features](#features)
@@ -150,7 +151,7 @@ Configure the action by customizing the following parameters based on your needs
     ]'
     ```
 
-### Features de/activation
+### Features De/Activation
 - **project-state-mining** (optional, `default: false`)
   - **Description**: Enables or disables the mining of project state data from [GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects).
   - **Usage**: Set to true to activate.
@@ -187,7 +188,7 @@ The Living Documentation Generator action provides a key output that allows user
 ## Expected Output
 The Living Documentation Generator is designed to produce an Issue Summary page (index.md) along with multiple detailed single issue pages.
 
-### Index page example
+### Index Page Example
 
 ```markdown
 # Issue Summary page
@@ -209,7 +210,7 @@ Here, you'll find a summarized list of all these issues, their brief description
 These values can vary from project to project.
 - The `---` symbol is used to indicate that an issue has no required project data.
 
-### Issue page example
+### Issue Page Example
 
 ```markdown
 # FEAT: Advanced Book Search
@@ -255,7 +256,7 @@ pip install -r requirements.txt
 ## Run Scripts Locally
 If you need to run the scripts locally, follow these steps:
 
-### Create the shell script
+### Create the Shell Script
 Create the shell file in the root directory. We will use `run_script.sh`.
 ```shell
 touch run_script.sh
@@ -265,7 +266,7 @@ Add the shebang line at the top of the sh script file.
 #!/bin/sh
 ```
 
-### Set the environment variables
+### Set the Environment Variables
 Set the configuration environment variables in the shell script following the structure below. 
 Also make sure that the GITHUB_TOKEN is configured in your environment variables.
 ```
@@ -305,7 +306,7 @@ chmod +x run_script.sh
 ```
 
 ## Run Pylint Check Locally
-This project uses Pylint tool for static code analysis.
+This project uses [Pylint](https://pypi.org/project/pylint/) tool for static code analysis.
 Pylint analyses your code without actually running it.
 It checks for errors, enforces, coding standards, looks for code smells etc. 
 
@@ -338,20 +339,71 @@ Example:
 pylint living_documentation_generator/generator.py
 ``` 
 
-## Run unit test
+### Expected Output
+This is the console expected output example after running the tool:
+```
+************* Module main
+main.py:30:0: C0116: Missing function or method docstring (missing-function-docstring)
+
+------------------------------------------------------------------
+Your code has been rated at 9.41/10 (previous run: 8.82/10, +0.59)
+```
+
+## Run Black Tool Locally
+This project uses the [Black](https://github.com/psf/black) tool for code formatting.
+Black aims for consistency, generality, readability and reducing git diffs.
+The coding style used can be viewed as a strict subset of PEP 8.
+
+The project root file `pyproject.toml` defines the Black tool configuration.
+In this project we are accepting the line length of 120 characters.
+
+Follow these steps to format your code with Black locally:
+
+### Set Up Python Environment
+From terminal in the root of the project, run the following command:
+
+```shell
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+This command will also install a Black tool, since it is listed in the project requirements.
+
+### Run Black
+Run Black on all files that are currently tracked by Git in the project.
+```shell
+black $(git ls-files '*.py')
+```
+
+To run Black on a specific file, follow the pattern `black <path_to_file>/<name_of_file>.py`.
+
+Example:
+```shell
+black living_documentation_generator/generator.py
+``` 
+
+### Expected Output
+This is the console expected output example after running the tool:
+```
+All done! ✨ 🍰 ✨
+1 file reformatted.
+```
+
+## Run Unit Test
 TODO - check this chapter and update by latest state
-### Launch unit tests
+### Launch Unit Tests
 ```
 pytest
 ```
 
-### To run specific tests or get verbose output:
+### To Run Specific Tests or Get Verbose Output:
 ```
 pytest -v  # Verbose mode
 pytest path/to/test_file.py  # Run specific test file
 ```
 
-### To check Test Coverage:
+### To Check Test Coverage:
 ```
 pytest --cov=../scripts
 ```

living_documentation_generator/action_inputs.py

@@ -1,3 +1,24 @@
+#
+# Copyright 2024 ABSA Group Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""
+This module contains an Action Inputs class methods,
+which are essential for running the GH action.
+"""
+
 import json
 import logging
 import sys
@@ -10,6 +31,10 @@
 
 
 class ActionInputs:
+    """
+    A class representing all the action inputs. It is responsible for loading, managing
+    and validating the inputs required for running the GH Action.
+    """
 
     def __init__(self):
         self.__github_token: str = ""
@@ -19,31 +44,40 @@ def __init__(self):
 
     @property
     def github_token(self) -> str:
+        """Getter of the GitHub authorization token."""
         return self.__github_token
 
     @property
     def is_project_state_mining_enabled(self) -> bool:
+        """Getter of the project state mining switch."""
         return self.__is_project_state_mining_enabled
 
     @property
     def repositories(self) -> list[ConfigRepository]:
+        """Getter of the list of repositories to fetch from."""
         return self.__repositories
 
     @property
     def output_directory(self) -> str:
+        """Getter of the output directory."""
         return self.__output_directory
 
-    def load_from_environment(self, validate: bool = True) -> 'ActionInputs':
+    def load_from_environment(self, validate: bool = True) -> "ActionInputs":
+        """
+        Load the action inputs from the environment variables and validate them if needed.
+
+        @param validate: Switch indicating if the inputs should be validated.
+        @return: The instance of the ActionInputs class.
+        """
         self.__github_token = get_action_input(GITHUB_TOKEN)
-        self.__is_project_state_mining_enabled = (get_action_input(PROJECT_STATE_MINING, "false")
-                                                  .lower() == "true")
-        out_path = get_action_input(OUTPUT_PATH, './output')
+        self.__is_project_state_mining_enabled = get_action_input(PROJECT_STATE_MINING, "false").lower() == "true"
+        out_path = get_action_input(OUTPUT_PATH, "./output")
         self.__output_directory = make_absolute_path(out_path)
         repositories_json = get_action_input(REPOSITORIES, "")
 
-        logger.debug('Is project state mining allowed: %s.', self.is_project_state_mining_enabled)
-        logger.debug('JSON repositories to fetch from: %s.', repositories_json)
-        logger.debug('Output directory: %s.', self.output_directory)
+        logger.debug("Is project state mining allowed: %s.", self.is_project_state_mining_enabled)
+        logger.debug("JSON repositories to fetch from: %s.", repositories_json)
+        logger.debug("Output directory: %s.", self.output_directory)
 
         # Validate inputs
         if validate:
@@ -64,6 +98,13 @@ def load_from_environment(self, validate: bool = True) -> 'ActionInputs':
         return self
 
     def validate_inputs(self, repositories_json: str) -> None:
+        """
+        Validate the input attributes of the action.
+
+        @param repositories_json: The JSON string containing the repositories to fetch.
+        @return: None
+        """
+
         # Validate correct format of input repositories_json
         try:
             json.loads(repositories_json)