Merge pull request #188 from StrangeRanger/dev

Author: StrangeRanger

README.md

@@ -42,7 +42,7 @@ The documentation includes:
 
 To build and preview the documentation locally, you'll need:
 
-- **Python**: Version 3.9 or higher
+- **Python**: Version 3.10 or higher
 - **[uv](https://github.com/astral-sh/uv#installation)**: For dependency management
 
 ### Download and Setup

pyproject.toml

@@ -3,7 +3,7 @@ name = "custom-unix-terminal"
 version = "2"
 description = "A project that uses mkdocs to host documentation for customizations of my Unix terminal."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
     "mkdocs-git-revision-date-localized-plugin==1.4.7",
     "mkdocs-material==9.6.16",

submodules/dotfiles

@@ -1,23 +1,34 @@
 #!/usr/bin/env python3
-#
-# Automates the process of updating zsh and neovim configuration files in the 'includes'
-# directory. This is done by reading my 'dotfiles' in the 'submodules/dotfiles'
-# submodule and applying the necessary changes to the 'includes' directory.
-#
-# NOTE:
-#   - This script does not require the initialization of a virtual environment. The
-#     Pipfiles are only required when deploying the MkDocs site.
-#   - This script has some hard-coded values that may make it fragile in some cases.
-#     I've attempted to do my best an indicate where these values are, but it's always a
-#     good idea to keep an eye on this script when making changes to the configuration.
-#
-########################################################################################
-# [ Imports ]###########################################################################
+"""Configuration file update automation script.
+
+This script automates the process of updating Neovim and zsh configuration files in the
+`includes` directory by extracting relevant sections from dotfiles stored in the
+`submodules/dotfiles` submodule.
+
+The script handles two main types of configuration updates:
+    - Neovim configuration files with selective content extraction
+    - Zsh configuration files with snippet-based processing
+
+Notes:
+    - This script is, unfortunately, fragile by nature. Changes to upstream marker text
+      or chezmoi template layout can silently break extractions. When this occurs,
+      adjust the markers in the constants module or update the `chezmoi_edge_case`
+      function as needed.
+    - No external dependencies are required; a virtual environment is not necessary.
+
+Example:
+    Run the script directly to update all configuration files:
 
+    ```bash
+    $ python3 update_repo.py
+    ```
+"""
 
-from utils.file_utils import read_file, write_file
+# [ Imports ]###########################################################################
+
+from utils.file_utils import read_file, read_lines, write_file
 from utils.constants import (
-    CHEZMOI_STATEMENTS,
+    CHEZMOI_DELIMITERS,
     NEOVIM_CONFIG_PATHS,
     ZSH_CONFIG_PATHS,
     NEOVIM_MARKERS,
@@ -31,15 +42,26 @@
 # [ Functions ]#########################################################################
 
 
-def neovim_config():
-    """Updates the neovim configuration files."""
-    for operation, paths in NEOVIM_CONFIG_PATHS.items():
-        data: list[str] | str = read_file(
-            paths["from"], read_lines=(operation == "init_vim_no_plug")
-        )
+def neovim_config() -> None:
+    """Process and write Neovim config file variants to the `includes` directory.
+
+    Handles two types of Neovim config processing:
+        1. `init_vim_no_plug`: Extracts content between designated section markers,
+           excluding plugin-related configurations.
+        2. Other variants: Copies the entire source file without modification.
+
+    The function iterates through all Neovim config paths defined in
+    `NEOVIM_CONFIG_PATHS` and processes each according to its operation type.
 
+    Note:
+        The `init_vim_no_plug` operation relies on `NEOVIM_MARKERS` to identify
+        content boundaries. The end marker line itself is excluded from output.
+    """
+    for operation, paths in NEOVIM_CONFIG_PATHS.items():
         if operation == "init_vim_no_plug":
+            data: list[str] = read_lines(paths["from"])
             filtered_data: list[str] = []
+
             for current_line in data:
                 if NEOVIM_MARKERS.start_marker in current_line:
                     NEOVIM_MARKERS.is_within_section = True
@@ -53,22 +75,30 @@ def neovim_config():
                     filtered_data.append(current_line)
             write_file(paths["to"], "".join(filtered_data))
         else:
+            data: str = read_file(paths["from"])
             write_file(paths["to"], data)
 
 
-def chezmoi_edge_case(current_line, data, line_number):
-    """Handles edge cases when chezmoi statements are encountered. These are hard coded
-    strings that need to be processed in a very specific way. This means that changes to
-    the configuration files can easily break or negate the functionality of this
-    method. Keep a close eye when making changes to the configuration files.
+def chezmoi_edge_case(current_line: str, data: list[str], line_number: int) -> int:
+    """Calculate the number of lines to skip for chezmoi template actions.
+
+    Handles special cases in chezmoi template processing by analyzing the current line
+    and subsequent lines to determine how many lines should be skipped during zsh
+    configuration processing.
+
+    Note:
+        This function's logic is tightly coupled to the current structure of the
+        dotfiles. Changes to the upstream chezmoi template layout may require updates
+        to the pattern matching logic.
 
     Args:
-        current_line (str): The line to process.
-        data (list[str]): The data from the file.
-        line_number (int): The current line number.
+        current_line: The current line being processed, which contains a chezmoi
+            template delimiter.
+        data: Complete list of lines from the source zsh configuration file.
+        line_number: Zero-based index of the current line within the data list.
 
     Returns:
-        int: The number of lines to skip.
+        Number of lines to skip (minimum 1).
     """
     if "data.isGUIEnvironment" in current_line:
         if (
@@ -85,24 +115,37 @@ def chezmoi_edge_case(current_line, data, line_number):
     return 1
 
 
-def zsh_config():
-    """Updates the zsh configuration files."""
+def zsh_config() -> None:
+    """Process and write zsh config file variants and snippets to the `includes`
+    directory.
+
+    Handles two types of processing:
+        1. Full file operations: Copies entire source file, filtering chezmoi template
+           actions.
+        2. Snippet operations: Extracts specific sections and wraps with MkDocs section
+           markers.
+
+    For snippet operations, extracts alias and `LS_COLORS` sections based on predefined
+    markers and optionally appends hard-coded content.
+
+    Note:
+        Includes debug output for CI/CD troubleshooting.
+    """
     for file_operation, file_paths in ZSH_CONFIG_PATHS.items():
-        data: list[str] | str = read_file(file_paths["from"], read_lines=True)
+        data: list[str] = read_lines(file_paths["from"])
         output_data: list[str] = []
         line_number = 0
 
         while line_number < len(data):
             current_line = data[line_number]
 
-            ## DEBUG: The below lines help with debugging, especially when running in a
-            ##  CI/CD environment.
+            ## DEBUG: The below lines help with debugging...
             print(f"Processing line {line_number + 1} of {file_paths['from']}")
             print(f"Line: {current_line}")
 
-            if any(marker in current_line for marker in CHEZMOI_STATEMENTS):
-                skip_line = chezmoi_edge_case(current_line, data, line_number)
-                line_number += skip_line
+            if any(marker in current_line for marker in CHEZMOI_DELIMITERS):
+                skip_line_count = chezmoi_edge_case(current_line, data, line_number)
+                line_number += skip_line_count
                 continue
 
             if not file_operation.endswith("snippet"):
@@ -143,8 +186,8 @@ def zsh_config():
         write_file(file_paths["to"], "".join(output_data))
 
 
-def main():
-    """Main function."""
+def main() -> None:
+    """Execute all configuration file update routines."""
     neovim_config()
     zsh_config()
 

update_repo.py

@@ -1,3 +1,3 @@
-__version__ = "1.0.5"
+__version__ = "1.1.0"
 __author__ = "Hunter T. (StrangeRanger)"
 __license__ = "MIT"

utils/__init__.py

@@ -1,9 +1,26 @@
+"""Configuration constants for update_repo.py.
+
+This module defines all the constants used by the update_repo.py script for processing
+configuration files from the dotfiles submodule. It includes:
+
+- File path mappings for Neovim and zsh configuration variants
+- Section markers for extracting specific content from configuration files
+- Template delimiters for identifying chezmoi template blocks
+- MkDocs content markers for generated documentation snippets
+
+The constants are organized by their functional purpose and are designed to be easily
+modified when upstream dotfile structures change.
+"""
+
 from pathlib import Path
-from utils.marker_config import Markers
+from typing import Final
+from utils.marker_config import SectionMarkers
 
-CHEZMOI_STATEMENTS = ["{{ ", "{{- "]
+# Chezmoi template delimiters to used to identify template blocks from my dotfiles.
+CHEZMOI_DELIMITERS: Final[list[str]] = ["{{ ", "{{- "]
 
-NEOVIM_CONFIG_PATHS = {
+# Maps Neovim config variants to their source and destination paths.
+NEOVIM_CONFIG_PATHS: Final[dict[str, dict[str, Path]]] = {
     "init_lua": {
         "from": Path("submodules/dotfiles/private_dot_config/nvim/second_init.lua"),
         "to": Path("includes/neovim-init-files/neovim-init-lua.lua"),
@@ -18,39 +35,41 @@
     },
 }
 
-ZSH_CONFIG_PATHS = {
+# Maps zsh config variants to their source and destination paths.
+ZSH_CONFIG_PATHS: Final[dict[str, dict[str, Path]]] = {
     "zshrc_linux": {
-        "from": Path("submodules/dotfiles/.zshrc_linux.tmpl"),
+        "from": Path("submodules/dotfiles/.chezmoitemplates/.zshrc_linux.tmpl"),
         "to": Path("includes/zshrc-files/zshrc-linux.zsh"),
     },
     "zshrc_linux_snippet": {
-        "from": Path("submodules/dotfiles/.zshrc_linux.tmpl"),
+        "from": Path("submodules/dotfiles/.chezmoitemplates/.zshrc_linux.tmpl"),
         "to": Path("includes/zshrc-files/zshrc-linux-snippet.zsh"),
     },
     "zshrc_macos": {
-        "from": Path("submodules/dotfiles/.zshrc_darwin.tmpl"),
+        "from": Path("submodules/dotfiles/.chezmoitemplates/.zshrc_darwin.tmpl"),
         "to": Path("includes/zshrc-files/zshrc-macos.zsh"),
     },
     "zshrc_macos_snippet": {
-        "from": Path("submodules/dotfiles/.zshrc_darwin.tmpl"),
+        "from": Path("submodules/dotfiles/.chezmoitemplates/.zshrc_darwin.tmpl"),
         "to": Path("includes/zshrc-files/zshrc-macos-snippet.zsh"),
     },
 }
 
-NEOVIM_MARKERS = Markers(
+# Section markers for the general configuration section in ``init.vim`` for snippet
+# extraction.
+NEOVIM_MARKERS: Final[SectionMarkers] = SectionMarkers(
     start_marker='""""[ General Configurations ]',
     end_marker='""""[ vim-plug Plugin Configurations ]',
 )
 
-ZSH_ALIAS_MARKERS = Markers(
+# Section markers for the aliases portion of ``.zshrc`` for snippet extraction.
+ZSH_ALIAS_MARKERS: Final[SectionMarkers] = SectionMarkers(
     start_marker="####[ Aliases ]",
     end_marker="####[ Environmental Variables ]",
 )
 
-# NOTE: This is an "estimated" value, that relies on the position of comments and other
-#   commands that may not always be present. Compared to the previous markers, this one
-#   is more likely to be wrong, if the `.zshrc` related files are modified.
-ZSH_LS_COLORS_MARKERS = Markers(
+# Section markers for extracting/injecting the LS_COLORS related lines.
+ZSH_LS_COLORS_MARKERS: Final[SectionMarkers] = SectionMarkers(
     start_marker="# Modifies the colors",
     end_marker="## Set default",
     hard_coded_inclusion=(
@@ -59,12 +78,14 @@
     ),
 )
 
-MKDOCS_USER_CONFIG_MARKERS = Markers(
+# Section markers used in generated MkDocs content for the user configuration snippet.
+MKDOCS_USER_CONFIG_MARKERS: Final[SectionMarkers] = SectionMarkers(
     start_marker="# --8<-- [start:user_config]\n",
     end_marker="# --8<-- [end:user_config]\n",
 )
 
-MKDOCS_LS_COLORS_MARKERS = Markers(
+# Section markers used in generated MkDocs content for the LS_COLORS snippet.
+MKDOCS_LS_COLORS_MARKERS: Final[SectionMarkers] = SectionMarkers(
     start_marker="# --8<-- [start:ls_colors]\n",
     end_marker="# --8<-- [end:ls_colors]\n",
 )

utils/constants.py

@@ -1,27 +1,49 @@
+"""File I/O utilities for the repository update automation system.
+
+This module provides simple, consistent wrappers around pathlib operations for
+reading and writing text files. These utilities are used throughout the project
+to handle configuration file processing with proper encoding support.
+
+All functions accept both string paths and pathlib.Path objects for flexibility.
+"""
+
 from pathlib import Path
+from typing import List
+
+
+def read_file(file_path: str | Path, encoding: str = "utf-8") -> str:
+    """Return the full text contents of ``file_path``.
+
+    Args:
+        file_path: Filesystem path or path-like string.
+        encoding: Text encoding used to decode the file (default UTF-8).
+
+    Returns:
+        The decoded file contents as a single string.
+    """
+    return Path(file_path).read_text(encoding=encoding)
 
 
-def read_file(file_path, read_lines=False):
-    """Reads the file and returns the data.
+def read_lines(file_path: str | Path, encoding: str = "utf-8") -> List[str]:
+    """Return file contents as a list of lines, preserving newline characters.
 
     Args:
-        file_path (Path): The path to the file.
-        read_lines (bool, optional): Whether to read the file line by line. Defaults to
-            False.
+        file_path: Filesystem path or path-like string.
+        encoding: Text encoding used to decode the file (default UTF-8).
 
     Returns:
-        list[str] | str: The data from the file.
+        List of lines including their terminating newlines where present.
     """
-    with open(file_path, "r") as file:
-        return file.readlines() if read_lines else file.read()
+    text = Path(file_path).read_text(encoding=encoding)
+    return text.splitlines(keepends=True)
 
 
-def write_file(file_path, data):
-    """Writes the data to the file.
+def write_file(file_path: str | Path, data: str, encoding: str = "utf-8") -> None:
+    """Write text to ``file_path``, creating the file if it doesn't exist.
 
     Args:
-        file_path (Path): The path to the file.
-        data (str): The data to write.
+        file_path: Destination path; parent directories must already exist.
+        data: Text to write.
+        encoding: Text encoding used to encode the file (default UTF-8).
     """
-    with open(file_path, "w") as file:
-        file.write(data)
+    Path(file_path).write_text(data, encoding=encoding)