[Penify] Full Repo Documentation

penify_hook/api_client.py

@@ -63,9 +63,9 @@ def generate_commit_summary(self, git_diff, instruction: str = "", repo_details
 
         Args:
             git_diff (str): The git diff of the commit.
-            instruction (str??): Additional instruction for the commit. Defaults to "".
-            repo_details (dict??): Details of the git repository. Defaults to None.
-            jira_context (dict??): JIRA issue details to enhance the commit summary. Defaults to None.
+            instruction (str?): Additional instruction for the commit. Defaults to "".
+            repo_details (dict?): Details of the git repository. Defaults to None.
+            jira_context (dict?): JIRA issue details to enhance the commit summary. Defaults to None.
 
         Returns:
             dict: The response from the API if the request is successful, None otherwise.

penify_hook/commands/auth_commands.py

@@ -12,11 +12,15 @@ def save_credentials(api_key):
     """Save or update the API keys in the .penify file in the user's home
     directory.
 
+    This function reads the existing .penify file (if it exists), updates
+    the API key, and writes it back to the file. If the file does not exist,
+    it creates a new one with the provided API key.
+
     Args:
         api_key (str): The new API key to be saved or updated.
 
     Returns:
-        bool: if the credentials were successfully saved, False otherwise.
+        bool: True if the credentials were successfully saved, False otherwise.
     """
     home_dir = Path.home()
     penify_file = home_dir / '.penify'

penify_hook/commands/commit_commands.py

@@ -8,22 +8,23 @@
 def commit_code(api_url, token, message, open_terminal, generate_description,
                llm_model=None, llm_api_base=None, llm_api_key=None,
                jira_url=None, jira_user=None, jira_api_token=None):
-    """Enhance Git commits with AI-powered commit messages.
+    """Generate enhanced Git commits with AI-powered commit messages.
 
-    This function allows for the generation of enhanced commit messages
-    using natural language processing models and optionally integrates with
-    JIRA for additional context. It processes the current Git folder to find
-    relevant files and generates a detailed commit message based on the
-    provided parameters.
+    This function processes the current Git folder to find relevant files
+    and generates a detailed commit message using natural language
+    processing models. It optionally integrates with JIRA for additional
+    context based on provided parameters. The function requires
+    authentication tokens for both the API and potentially JIRA.
 
     Args:
         api_url (str): URL of the API endpoint.
         token (str): Authentication token for the API.
         message (str): Initial commit message provided by the user.
         open_terminal (bool): Whether to open the terminal after committing.
-        generate_description (bool): Whether to generate a detailed description in the commit message.
-        llm_model (str?): The language model to use for generating the commit message. Defaults to
-            None.
+        generate_description (bool): Whether to generate a detailed description
+            in the commit message.
+        llm_model (str?): The language model to use for generating the
+            commit message. Defaults to None.
         llm_api_base (str?): Base URL of the LLM API. Defaults to None.
         llm_api_key (str?): API key for accessing the LLM service. Defaults to None.
         jira_url (str?): URL of the JIRA instance. Defaults to None.

penify_hook/commands/config_commands.py

@@ -95,7 +95,8 @@ def save_jira_config(url, username, api_token):
 
     This function reads existing JIRA configuration from the .penify file,
     updates or adds new JIRA configuration details, and writes it back to
-    the file.
+    the file. If the .penify file does not exist or is invalid JSON, it will
+    be created or corrected.
 
     Args:
         url (str): The URL of the JIRA instance.
@@ -157,11 +158,12 @@ def get_llm_config():
     return {}
 
 def get_jira_config():
-    """Get JIRA configuration from the .penify file.
+    """Retrieve JIRA configuration from a JSON file specified in the .penify
+    file.
 
-    This function reads the JIRA configuration from a JSON file specified in
-    the .penify file. If the .penify file exists and contains valid JSON
-    with a 'jira' key, it returns the corresponding configuration.
+    This function reads the JIRA configuration from a JSON file designated
+    in the .penify file. If the .penify file is present and contains valid
+    JSON with a 'jira' key, it returns the corresponding configuration.
     Otherwise, it returns an empty dictionary.
 
     Returns:
@@ -184,7 +186,7 @@ def config_llm_web():
     This function starts a temporary HTTP server that serves an HTML
     template for configuring Large Language Model (LLM) settings. It handles
     GET and POST requests to retrieve the current configuration, save new
-    configurations, and suppress log messages.  The server runs on a random
+    configurations, and suppress log messages. The server runs on a random
     port between 30000 and 50000, and it is accessible via a URL like
     http://localhost:<redirect_port>. The function opens this URL in the
     default web browser for configuration. Once configured, the server shuts
@@ -328,8 +330,8 @@ def do_GET(self):
 
             This function processes GET requests based on the path requested. It
             serves an HTML template for the root path, returns a JSON configuration
-            for a specific endpoint, and handles any other paths by returning a 404
-            error.
+            for a specific endpoint ("/get_config"), and handles any other paths by
+            returning a 404 error.
             """
 
             if self.path == "/":
@@ -437,7 +439,7 @@ def log_message(self, format, *args):
     print("Configuration completed.")
 
 def get_token():
-    """Get the token based on priority from environment variables or
+    """Get the API token based on priority from environment variables or
     configuration files.
 
     Returns:

penify_hook/commands/doc_commands.py

@@ -6,18 +6,17 @@
 def generate_doc(api_url, token, location=None):
     """Generates documentation based on the given parameters.
 
-    This function initializes an API client using the provided API URL and
-    token. It then generates documentation by analyzing the specified
-    location, which can be a folder, a file, or the current working
-    directory if no location is provided. The function handles different
-    types of analysis based on the input location and reports any errors
-    encountered during the process.
+    Initializes an API client using the provided API URL and token. It then
+    generates documentation by analyzing the specified location (folder,
+    file, or current working directory if not provided), handling different
+    types of analysis, and reporting any errors encountered during the
+    process.
 
     Args:
         api_url (str): The URL of the API to connect to for documentation generation.
         token (str): The authentication token for accessing the API.
-        location (str?): The path to a specific file or folder to analyze. If not provided, the
-            current working directory is used.
+        location (str??): The path to a specific file or folder to analyze. If not provided,
+            the current working directory is used.
     """
 
     import os
@@ -90,6 +89,10 @@ def setup_docgen_parser(parser):
 
     Args:
         parser (argparse.ArgumentParser): The parser to configure.
+
+    Returns:
+        None: This function does not return anything but configures the provided
+            parser.
     """
 
     # We don't need to create a new docgen_parser since it's passed as a parameter

penify_hook/commands/hook_commands.py

@@ -12,7 +12,11 @@
 def install_git_hook(location, token):
     """Install a post-commit hook in the specified location that generates
     documentation
-    for changed files after each commit.
+    for changed files after each commit.  This function creates a new file
+    named 'post-commit' in the '.git/hooks' directory of the specified Git
+    repository. The hook script will use the provided authentication token
+    to access and generate documentation for any changes made during
+    commits.
 
     Args:
         location (str): The path to the Git repository where the hook should be installed.

penify_hook/commit_analyzer.py

@@ -113,6 +113,11 @@ def run(self, msg: Optional[str], edit_commit_message: bool, generate_descriptio
     def process_jira_integration(self, title: str, description: str, msg: str) -> tuple:
         """Process JIRA integration for the commit message.
 
+        This function processes the provided commit title, description, and user
+        message to look for JIRA issue keys. It extracts issue keys from the
+        message content, branch name, and adds comments to the corresponding
+        JIRA issues.
+
         Args:
             title (str): Generated commit title.
             description (str): Generated commit description.

penify_hook/file_analyzer.py

@@ -103,10 +103,10 @@ def process_file(self, file_path, pbar):
             return False
 
     def print_processing(self, file_path):
-        """Print a processing message for a file.
+        """Print a processing message for a specified file.
 
         Args:
-            file_path (str): The path to the file being processed.
+            file_path (str): The path to the file that is being processed.
         """
         formatted_path = format_file_path(file_path)
         print(f"\n{format_highlight(f'Processing file: {formatted_path}')}")

penify_hook/folder_analyzer.py

@@ -14,18 +14,19 @@ def __init__(self, dir_path: str, api_client: APIClient):
     def list_all_files_in_dir(self, dir_path: str):
         """List all non-hidden files in a directory and its subdirectories.
 
-        This function recursively traverses the specified directory and its
-        subdirectories, collecting paths of all non-hidden files. It filters out
-        hidden directories and files (those starting with a dot) to ensure only
-        visible files are returned.
+        Recursively traverses the specified directory and its subdirectories,
+        collecting paths of all non-hidden files. Hidden directories and files
+        (those starting with a dot) are excluded to ensure only visible files
+        are returned.
 
         Args:
             dir_path (str): The path to the directory whose files and subdirectory files need to be
                 listed.
 
         Returns:
             list: A list containing the full paths of all non-hidden files within the
-                specified directory and its subdirectories.
+                specified directory
+                and its subdirectories.
         """
 
         files = []

penify_hook/git_analyzer.py

@@ -92,13 +92,12 @@ def process_file(self, file_path):
         """Process a file by checking its type, reading its content, and sending it
         to an API.
 
-        This method constructs the absolute path of the specified file and
-        verifies if the file has a valid extension. If the file type is
-        supported, it reads the content of the file and retrieves the
-        differences from the last commit in the repository. If changes are
-        detected, it sends the file content along with the modified lines to an
-        API for further processing. If the API response indicates no changes,
-        the original file will not be overwritten.
+        This method constructs the absolute path of the specified file, verifies
+        if the file has a valid extension, reads the content of the file,
+        retrieves the differences from the last commit in the repository. If
+        changes are detected, it sends the file content along with the modified
+        lines to an API for further processing. If the API response indicates no
+        changes, the original file will not be overwritten.
 
         Args:
             file_path (str): The relative path to the file to be processed.
@@ -160,6 +159,9 @@ def run(self):
         processing, printing an error message for each file that fails to
         process. If any modifications are made to the files, an auto-commit is
         created to save those changes.
+
+        Args:
+            self (DocGenHook): An instance of the DocGenHook class.
         """
         logger.info("Starting doc_gen_hook processing")
         print_info("Starting doc_gen_hook processing")

penify_hook/jira_client.py

@@ -51,18 +51,17 @@ def is_connected(self) -> bool:
         and `False` otherwise.
 
         Returns:
-            bool: True if the JIRA client is connected, False otherwise
+            bool: True if the JIRA client is connected, False otherwise.
         """
         return self.jira_client is not None
 
     def extract_issue_keys_from_branch(self, branch_name: str) -> List[str]:
         """Extracts JIRA issue keys from a branch name.
 
-        This function searches through a given git branch name to find and
-        return any JIRA issue keys that match the pattern. Common conventions
-        for JIRA issue keys in branch names include: -
-        feature/PROJECT-123-description - bugfix/PROJECT-123-fix-something -
-        hotfix/PROJECT-123/short-desc
+        Searches through a given git branch name to find and return any JIRA
+        issue keys that match the pattern. Common conventions for JIRA issue
+        keys in branch names include: - feature/PROJECT-123-description -
+        bugfix/PROJECT-123-fix-something - hotfix/PROJECT-123/short-desc
 
         Args:
             branch_name (str): The name of the git branch to search for JIRA issue keys.
@@ -146,11 +145,11 @@ def add_comment(self, issue_key: str, comment: str) -> bool:
         """Add a comment to a JIRA issue.
 
         Args:
-            issue_key (str): JIRA issue key (e.g., "PROJECT-123")
-            comment (str): Comment text to add
+            issue_key (str): The JIRA issue key (e.g., "PROJECT-123").
+            comment (str): The text of the comment to be added.
 
         Returns:
-            bool: True if the comment was added successfully, False otherwise
+            bool: True if the comment was added successfully, False otherwise.
         """
         if not self.is_connected():
             logging.warning("JIRA client not connected")

penify_hook/llm_client.py

@@ -26,7 +26,7 @@ def __init__(self, model: str = None, api_base: str = None, api_key: str = None)
             os.environ["OPENAI_API_KEY"] = api_key
 
     def generate_commit_summary(self, diff: str, message: str, generate_description: bool, repo_details: Dict, jira_context: Dict = None) -> Dict:
-        """Generate a commit summary using the LLM.
+        """Generates a commit summary using the LLM.
 
         This function generates a concise and descriptive commit summary based
         on the provided Git diff, user instructions, repository details, and
@@ -46,7 +46,7 @@ def generate_commit_summary(self, diff: str, message: str, generate_description:
         Returns:
             Dict: A dictionary containing the title and description for the commit. If
                 generate_description is False,
-                the 'description' key may be absent.
+            the 'description' key may be absent.
 
         Raises:
             ValueError: If the LLM model is not configured.

penify_hook/login_command.py

@@ -13,8 +13,8 @@ def handle_login(args):
         args (argparse.Namespace): Parsed arguments containing necessary parameters for the login command.
 
     Returns:
-        None: This function does not return any value; it is expected to handle the
-            login process internally.
+        None: This function does not return any value; it is expected to handle
+            the login process internally.
     """
 
     from penify_hook.constants import API_URL, DASHBOARD_URL

penify_hook/main.py

@@ -7,11 +7,11 @@ def main():
     """Main function to handle command-line interface (CLI) interactions with
     Penify services.
 
-    This tool provides a command-line interface for generating smart commit
-    messages, configuring local-LLM and JIRA, and generating code
-    documentation. It supports basic commands that do not require login and
-    advanced commands that require user authentication. The `--version` flag
-    can be used to display the version information.
+    This tool provides a comprehensive command-line interface for generating
+    smart commit messages, configuring local-LLM and JIRA, and generating
+    code documentation. It supports both basic commands that do not require
+    login and advanced commands that require user authentication. The
+    `--version` flag can be used to display the version information.
 
     Returns:
         int: Exit status of the program (0 for success, 1 for error).

penify_hook/ui_utils.py

@@ -82,6 +82,10 @@ def format_error(message):
 def format_highlight(message):
     """Format a highlighted message with appropriate color.
 
+    This function takes a message and wraps it in ANSI escape codes to apply
+    a highlight style. The highlighting is reset afterward using
+    Style.RESET_ALL.
+
     Args:
         message (str): The message to be formatted and highlighted.
 
@@ -188,7 +192,11 @@ def print_status(status, message):
         print(f"  {PROCESSING_SYMBOL} {message}")
 
 def create_progress_bar(total, desc="Processing", unit="item"):
-    """Create a tqdm progress bar with consistent styling.
+    """Create a consistent tqdm progress bar.
+
+    This function generates and returns a configured tqdm progress bar with
+    customizable total, description, and unit. The progress bar is formatted
+    with a fixed width and uses ASCII characters for rendering.
 
     Args:
         total (int): Total number of items to process.
@@ -197,6 +205,13 @@ def create_progress_bar(total, desc="Processing", unit="item"):
 
     Returns:
         tqdm: A configured tqdm progress bar instance.
+
+    Examples:
+        >>> from tqdm import tqdm
+        >>> pbar = create_progress_bar(100, desc="Downloading", unit="file")
+        >>> for i in range(100):
+        ...     time.sleep(0.1)
+        ...     pbar.update(1)
     """
     return tqdm(
         total=total,
@@ -210,9 +225,9 @@ def create_stage_progress_bar(stages, desc="Processing"):
     """Create a tqdm progress bar for processing stages with consistent
     styling.
 
-    This function initializes and returns a tqdm progress bar object for
-    tracking the progress through a series of stages. It also provides a
-    description for the progress bar to enhance its usability.
+    Initialize and returns a tqdm progress bar object to track the progress
+    through a series of stages. Optionally provide a description to enhance
+    its usability.
 
     Args:
         stages (list): A list of strings representing individual stages in the process.