|
| 1 | +#!/usr/bin/env python3 |
| 2 | + |
| 3 | +import subprocess |
| 4 | +import hashlib |
| 5 | +import os |
| 6 | +import sys |
| 7 | + |
| 8 | +# --- Configuration --- |
| 9 | +# Define the directory where the Markdown and checksum files will be stored. |
| 10 | +# This will create 'doc/guides' relative to your repository root. |
| 11 | +DOCS_DIR = os.path.join("doc", "guides") |
| 12 | + |
| 13 | +# Define the directory for checksums within the docs directory. |
| 14 | +# This will create 'doc/guides/checksums'. |
| 15 | +CHECKSUMS_DIR = os.path.join(DOCS_DIR, "checksums") |
| 16 | + |
| 17 | +# Define the filename for the generated Rake tasks Markdown file. |
| 18 | +RAKE_MD_FILENAME = "rake-tasks.md" |
| 19 | + |
| 20 | +# Construct the full path for the Markdown file. |
| 21 | +RAKE_MD_PATH = os.path.join(DOCS_DIR, RAKE_MD_FILENAME) |
| 22 | + |
| 23 | +# Define the filename for the checksum file. |
| 24 | +CHECKSUM_FILENAME = f"{RAKE_MD_FILENAME}.sha256" |
| 25 | + |
| 26 | +# Construct the full path for the checksum file. |
| 27 | +CHECKSUM_PATH = os.path.join(CHECKSUMS_DIR, CHECKSUM_FILENAME) |
| 28 | + |
| 29 | +# --- Helper Functions --- |
| 30 | + |
| 31 | +def run_rake_tasks(): |
| 32 | + """ |
| 33 | + Executes the 'rake -T' command and captures its standard output. |
| 34 | + Handles cases where 'rake' is not found or the command fails. |
| 35 | + """ |
| 36 | + print("Running 'rake -T' to capture task list...") |
| 37 | + try: |
| 38 | + # subprocess.run executes the command. |
| 39 | + # capture_output=True redirects stdout and stderr. |
| 40 | + # text=True decodes stdout/stderr as text using default encoding. |
| 41 | + # check=True raises CalledProcessError if the command returns a non-zero exit code. |
| 42 | + result = subprocess.run(["rake", "-T"], capture_output=True, text=True, check=True) |
| 43 | + print("Successfully captured Rake tasks.") |
| 44 | + return result.stdout |
| 45 | + except FileNotFoundError: |
| 46 | + # Error if 'rake' command is not found in the system's PATH. |
| 47 | + print("Error: 'rake' command not found. Please ensure Rake is installed and in your PATH.", file=sys.stderr) |
| 48 | + sys.exit(1) # Exit with a non-zero code to indicate failure to the pre-commit hook. |
| 49 | + except subprocess.CalledProcessError as e: |
| 50 | + # Error if 'rake -T' command itself fails (e.g., syntax errors in Rakefiles). |
| 51 | + print(f"Error running 'rake -T':\n{e.stderr}", file=sys.stderr) |
| 52 | + sys.exit(1) # Exit with a non-zero code. |
| 53 | + |
| 54 | +def generate_markdown_file(output): |
| 55 | + """ |
| 56 | + Creates or updates the RAKE_TASKS.md file with the captured Rake output. |
| 57 | + The content includes a header and the raw output embedded in a Markdown code block. |
| 58 | + """ |
| 59 | + print(f"Generating Markdown file: {RAKE_MD_PATH}...") |
| 60 | + # Ensure the directory structure exists. `exist_ok=True` prevents an error if it already exists. |
| 61 | + os.makedirs(DOCS_DIR, exist_ok=True) |
| 62 | + |
| 63 | + # Construct the full Markdown content. |
| 64 | + markdown_content = f"""# Rake Tasks |
| 65 | +
|
| 66 | +This file is automatically generated by a pre-commit hook. Do not edit manually. |
| 67 | +
|
| 68 | +``` |
| 69 | +{output.strip()} |
| 70 | +``` |
| 71 | +""" |
| 72 | + # Write the content to the Markdown file. |
| 73 | + with open(RAKE_MD_PATH, "w") as f: |
| 74 | + f.write(markdown_content) |
| 75 | + print(f"Successfully generated {RAKE_MD_PATH}") |
| 76 | + |
| 77 | +def calculate_sha256(filepath): |
| 78 | + """ |
| 79 | + Calculates the SHA256 hash of a given file. |
| 80 | + Reads the file in chunks to handle potentially large files efficiently. |
| 81 | + """ |
| 82 | + hasher = hashlib.sha256() |
| 83 | + # Open the file in binary read mode. |
| 84 | + with open(filepath, "rb") as f: |
| 85 | + # Read the file in 8KB chunks until the end. |
| 86 | + while chunk := f.read(8192): |
| 87 | + hasher.update(chunk) # Update the hash with each chunk. |
| 88 | + return hasher.hexdigest() # Return the hexadecimal representation of the hash. |
| 89 | + |
| 90 | +def generate_checksum_file(): |
| 91 | + """ |
| 92 | + Generates a SHA256 checksum file for RAKE_TASKS.md. |
| 93 | + The checksum is stored in a separate file in the 'checksums' subdirectory. |
| 94 | + """ |
| 95 | + print(f"Generating checksum file: {CHECKSUM_PATH}...") |
| 96 | + # Ensure the checksums directory exists. |
| 97 | + os.makedirs(CHECKSUMS_DIR, exist_ok=True) |
| 98 | + |
| 99 | + # Calculate the checksum of the Markdown file. |
| 100 | + checksum = calculate_sha256(RAKE_MD_PATH) |
| 101 | + |
| 102 | + # Write the checksum to its dedicated file. |
| 103 | + with open(CHECKSUM_PATH, "w") as f: |
| 104 | + f.write(checksum) |
| 105 | + print(f"Successfully generated {CHECKSUM_PATH}") |
| 106 | + |
| 107 | +# --- Main Execution --- |
| 108 | + |
| 109 | +def main(): |
| 110 | + """ |
| 111 | + Main function to orchestrate the Rake documentation generation process. |
| 112 | + """ |
| 113 | + # Step 1: Run 'rake -T' and get its output. |
| 114 | + rake_output = run_rake_tasks() |
| 115 | + |
| 116 | + # Step 2: Generate the Markdown file with the captured Rake output. |
| 117 | + generate_markdown_file(rake_output) |
| 118 | + |
| 119 | + # Step 3: Generate the checksum file for the newly created Markdown file. |
| 120 | + generate_checksum_file() |
| 121 | + |
| 122 | + # If the script reaches this point, it means all operations (running rake, |
| 123 | + # generating markdown, and generating checksum) were successful. |
| 124 | + # The pre-commit framework will automatically check if these newly generated |
| 125 | + # files are unstaged. If they are, it will fail the commit and prompt the |
| 126 | + # user to 'git add' them. This is the standard and recommended behavior. |
| 127 | + print("\nRake documentation generation complete.") |
| 128 | + sys.exit(0) # Exit with 0 to indicate success to the pre-commit hook. |
| 129 | + |
| 130 | +if __name__ == "__main__": |
| 131 | + main() |
0 commit comments