Refactoring/13 documentation and formatting

.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)
@@ -76,12 +77,6 @@ See the full example of action step definition (in example are used non-default
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
   with:
-    # project state mining de/activation
-    project-state-mining: true
-
-    # project verbose (debug) logging de/activation
-    verbose-logging: true
-
     # input repositories + feature to filter projects
     repositories: '[
       {
@@ -156,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.
@@ -193,23 +188,29 @@ 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
 
 Our project is designed with a myriad of issues to ensure seamless user experience, top-tier functionality, and efficient operations.
 Here, you'll find a summarized list of all these issues, their brief descriptions, and links to their detailed documentation.
 
 ## Issue Overview
-| Organization name| Repository name            | Issue 'Number - Title'                        | Linked to project | Project Status | Issue URL  |
-|------------------|----------------------------|-----------------------------------------------|-------------------|----------------|------------|
-|AbsaOSS           | living-doc-example-project | [#89 - Test issue 2](89_test_issue_2.md)      | 🔴                | ---            |[GitHub](#) |
-|AbsaOSS           | living-doc-example-project | [#88 - Test issue](88_test_issue.md)          | 🟢                | Todo           |[GitHub](#) |
-|AbsaOSS           | living-doc-example-project | [#41 - Initial commit.](41_initial_commit.md) | 🟢                | Done           |[GitHub](#) |
-|AbsaOSS           | living-doc-example-project | [#33 - Example bugfix](33_example_bugfix.md)  | 🔴                | ---            |[GitHub](#) |
+
+| Organization name| Repository name            | Issue 'Number - Title'         | Linked to project | Project Status | Issue URL  |
+|------------------|----------------------------|--------------------------------|-------------------|----------------|------------|
+| AbsaOSS          | living-doc-example-project | [#89 - Test issue 2](89_test_issue_2.md)      | 🔴 | ---            |[GitHub](#) |
+| AbsaOSS          | living-doc-example-project | [#88 - Test issue](88_test_issue.md)          | 🟢 | Todo           |[GitHub](#) |
+| AbsaOSS          | living-doc-example-project | [#41 - Initial commit.](41_initial_commit.md) | 🟢 | Done           |[GitHub](#) |
+| AbsaOSS          | living-doc-example-project | [#33 - Example bugfix](33_example_bugfix.md)  | 🔴 | ---            |[GitHub](#) |
 ```
 
-### Issue page example
+- **Project Status** can have various values depending on the project, such as: Todo, Done, Closed, In Progress, In Review, Blocked, etc. 
+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
 
 ```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,13 +266,11 @@ 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.
 ```
 export INPUT_GITHUB_TOKEN=$(printenv GITHUB_TOKEN)
-export INPUT_PROJECT_STATE_MINING="true"
-export INPUT_VERBOSE_LOGGING="true"
 export INPUT_REPOSITORIES='[
             {
               "organization-name": "Organization Name",
@@ -340,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 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

@@ -15,19 +15,16 @@
 #
 
 """
-This module contains the ActionInputs class which is responsible for loading, managing and validating the inputs
-required for running the GH Action.
+This module contains an Action Inputs class methods,
+which are essential for running the GH action.
 """
 
 import json
 import logging
 import sys
 
 from living_documentation_generator.model.config_repository import ConfigRepository
-from living_documentation_generator.utils.utils import (
-    get_action_input,
-    make_absolute_path,
-)
+from living_documentation_generator.utils.utils import get_action_input, make_absolute_path
 from living_documentation_generator.utils.constants import (
     GITHUB_TOKEN,
     PROJECT_STATE_MINING,
@@ -40,14 +37,10 @@
 
 class ActionInputs:
     """
-    A class representing all inputs that are essential for running the GH action.
-
-    Attributes:
-        __github_token (str): The GitHub token used for authentication.
-        __is_project_state_mining_enabled (bool): Switch indicating if project state mining is enabled.
-        __repositories (list[ConfigRepository]): List of config repositories to fetch from.
-        __output_directory (str): The directory where the markdown pages will be stored.
+    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 = ""
         self.__is_project_state_mining_enabled: bool = False
@@ -78,13 +71,11 @@ def load_from_environment(self, validate: bool = True) -> "ActionInputs":
         """
         Load the action inputs from the environment variables and validate them if needed.
 
-        Args:
-            validate (bool): Switch indicating if the inputs should be validated.
+        @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"
-        )
+        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, "")
@@ -115,8 +106,8 @@ def validate_inputs(self, repositories_json: str) -> None:
         """
         Validate the input attributes of the action.
 
-        Args:
-            repositories_json(str): The JSON string containing the repositories to fetch.
+        @param repositories_json: The JSON string containing the repositories to fetch.
+        @return: None
         """
 
         # Validate correct format of input repositories_json