Auto create Markdown based hook docs with pre-commit

.github/workflows/scripts/create_pre_commit_docs.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+
+import yaml
+
+
+def generate_pre_commit_table(yaml_path):
+    """
+    Generates a Markdown table from a pre-commit-config.yaml file.
+    """
+    try:
+        with open(yaml_path) as f:
+            config = yaml.safe_load(f)
+    except FileNotFoundError:
+        return f"Error: The file '{yaml_path}' was not found."
+    except yaml.YAMLError as e:
+        return f"Error parsing YAML file: {e}"
+
+    table_header = "| Hook ID | Language | Description | Version |\n"
+    table_separator = "|---|---|---|---|\n"
+    table_rows = []
+
+    for repo in config.get("repos", []):
+        version = repo.get("rev", "N/A")
+        url = repo.get("repo", "N/A")
+        for hook in repo.get("hooks", []):
+            hook_id = hook.get("id", "N/A")
+            language = hook.get("language", "N/A")
+            description = hook.get("description", "N/A")
+            if description == "N/A":
+                description = hook.get("name", "N/A")
+            # args = ", ".join(hook.get("args", [])) if hook.get("args") else "N/A"
+
+            if url not in ["local", "meta"]:
+                entry = f"[{hook_id}]({url})"
+            else:
+                entry = f"{hook_id}"
+
+            table_rows.append(f"| {entry} | {language} | {description} | {version} |\n")
+
+    return table_header + table_separator + "".join(table_rows)
+
+
+def create_markdown_file(target_file_path, content_to_append):
+    """
+    Creates a Markdown file with the content.
+    """
+    try:
+        with open(target_file_path, "w+") as f:
+            f.seek(0)
+            f.write(
+                """<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you 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.
+ -->
+
+# pre-commit hook documentation
+
+ """
+            )
+            f.write(content_to_append)
+        return f"File content successfully created at '{target_file_path}'."
+    except OSError as e:
+        return f"Error creating file: {e}"
+
+
+if __name__ == "__main__":
+
+    pre_commit_yaml_path = (
+        ".pre-commit-config.yaml"  # Assuming this file is in the same directory
+    )
+    output_markdown_path = "PRE_COMMIT_HOOK_DOCS.md"
+
+    # Generate the Markdown table
+    markdown_table = generate_pre_commit_table(pre_commit_yaml_path)
+
+    # Add the table to the target Markdown file
+    if "Error" not in markdown_table:
+        result = create_markdown_file(output_markdown_path, markdown_table)
+        print(result)
+    else:
+        print(markdown_table)

.pre-commit-config.yaml

@@ -24,13 +24,26 @@ repos:
   - repo: meta
     hooks:
       - id: identity
+        description: a simple hook which prints all arguments passed to it, useful for debugging.
       - id: check-hooks-apply
+        description: check that all the hooks apply to the repository
   - repo: https://github.com/thlorenz/doctoc.git
     rev: v2.2.0
     hooks:
       - id: doctoc
         name: Add TOC for Markdown files
+        description: automatically keeps your table of contents up to date
         files: ^CONTRIBUTING\.md$|^INSTALL\.md$|^README\.md$
+  - repo: local
+    hooks:
+      - id: create-pre-commit-docs
+        name: create pre-commit docs
+        description: creates a Markdown file with information on the pre-commit hooks
+        entry: .github/workflows/scripts/create_pre_commit_docs.py
+        language: python
+        additional_dependencies:
+          - pyyaml
+        require_serial: true
   - repo: https://github.com/oxipng/oxipng
     rev: v9.1.5
     hooks:
@@ -49,11 +62,13 @@ repos:
     hooks:
       - id: chmod
         name: set file permissions
+        description: manual hook to be run by macOS or Linux users for a full repository clean up
         args: ['644']
         files: \.md$
         stages: [manual]
       - id: insert-license
         name: add license for all Markdown files
+        description: automatically adds a licence header to all Markdown files that don't have a license header
         files: \.md$
         args:
           - --comment-style
@@ -74,6 +89,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all SQL files
+        description: automatically adds a licence header to all SQL files that don't have a license header
         files: \.sql$
         args:
           - --comment-style
@@ -96,18 +112,27 @@ repos:
     hooks:
       #- id: check-added-large-files
       - id: check-case-conflict
+        description: check for case conflicts in file names
       #- id: check-executables-have-shebangs
       - id: check-illegal-windows-names
+        description: check for Windows-illegal file names
       - id: check-merge-conflict
+        description: check for merge conflict markers
       - id: check-shebang-scripts-are-executable
+        description: check that scripts with shebangs are executable
         files: \.sh$
       - id: check-symlinks
+        description: checks for symlinks which do not point to anything.
       - id: check-vcs-permalinks
+        description: ensures that links to vcs websites are permalinks
       #- id: check-yaml
       - id: destroyed-symlinks
+        description: detects symlinks which are changed to regular files with a content of a path which that symlink was pointing to
       - id: detect-aws-credentials
+        description: checks for the existence of AWS secrets that you have set up with the AWS CLI
         args: [--allow-missing-credentials]
       - id: detect-private-key
+        description: checks for the existence of private keys
         exclude: >
           (?x)
           ^scripts/vm/systemvm/id_rsa\.cloud$|
@@ -124,14 +149,20 @@ repos:
           ^systemvm/agent/certs/realhostip\.key$|
           ^test/integration/smoke/test_ssl_offloading\.py$
       - id: end-of-file-fixer
+        description: makes sure files end in a newline and only a newline
         exclude: \.vhd$|\.svg$
       - id: file-contents-sorter
+        description: sort the lines in specified files (defaults to alphabetical)
         args: [--unique]
         files: ^\.github/linters/codespell\.txt$
       - id: fix-byte-order-marker
+        description: removes UTF-8 byte order marker
       - id: forbid-submodules
+        description: forbids any submodules in the repository
       - id: mixed-line-ending
+        description: replaces or checks mixed line ending
       - id: trailing-whitespace
+        description: trims trailing whitespace
         files: \.(bat|cfg|cs|css|gitignore|header|in|install|java|md|properties|py|rb|rc|sh|sql|te|template|txt|ucls|vue|xml|xsl|yaml|yml)$|^cloud-cli/bindir/cloud-tool$|^debian/changelog$
         args: [--markdown-linebreak-ext=md]
         exclude: ^services/console-proxy/rdpconsole/src/test/doc/freerdp-debug-log\.txt$
@@ -147,6 +178,7 @@ repos:
     rev: 7.0.0
     hooks:
     - id: flake8
+      description: flake8 is a Python tool that glues together pycodestyle, pyflakes, mccabe, and third-party plugins to check the style and quality of some python code
       args: [--config, .github/linters/.flake8]
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: v0.45.0

PRE_COMMIT_HOOK_DOCS.md

@@ -0,0 +1,53 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you 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.
+ -->
+
+# pre-commit hook documentation
+
+ | Hook ID | Language | Description | Version |
+|---|---|---|---|
+| identity | N/A | a simple hook which prints all arguments passed to it, useful for debugging. | N/A |
+| check-hooks-apply | N/A | check that all the hooks apply to the repository | N/A |
+| [doctoc](https://github.com/thlorenz/doctoc.git) | N/A | automatically keeps your table of contents up to date | v2.2.0 |
+| create-pre-commit-docs | python | creates a Markdown file with information on the pre-commit hooks | N/A |
+| [oxipng](https://github.com/oxipng/oxipng) | N/A | optimize PNG images with lossless compression | v9.1.5 |
+| [gitleaks](https://github.com/gitleaks/gitleaks) | N/A | detect hardcoded secrets | v8.27.2 |
+| [chmod](https://github.com/Lucas-C/pre-commit-hooks) | N/A | manual hook to be run by macOS or Linux users for a full repository clean up | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | automatically adds a licence header to all Markdown files that don't have a license header | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | automatically adds a licence header to all Shell files that don't have a license header | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | automatically adds a licence header to all SQL files that don't have a license header | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | automatically adds a licence header to all YAML files that don't have a license header | v1.5.5 |
+| [check-case-conflict](https://github.com/pre-commit/pre-commit-hooks) | N/A | check for case conflicts in file names | v6.0.0 |
+| [check-illegal-windows-names](https://github.com/pre-commit/pre-commit-hooks) | N/A | check for Windows-illegal file names | v6.0.0 |
+| [check-merge-conflict](https://github.com/pre-commit/pre-commit-hooks) | N/A | check for merge conflict markers | v6.0.0 |
+| [check-shebang-scripts-are-executable](https://github.com/pre-commit/pre-commit-hooks) | N/A | check that scripts with shebangs are executable | v6.0.0 |
+| [check-symlinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | checks for symlinks which do not point to anything. | v6.0.0 |
+| [check-vcs-permalinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | ensures that links to vcs websites are permalinks | v6.0.0 |
+| [destroyed-symlinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | detects symlinks which are changed to regular files with a content of a path which that symlink was pointing to | v6.0.0 |
+| [detect-aws-credentials](https://github.com/pre-commit/pre-commit-hooks) | N/A | checks for the existence of AWS secrets that you have set up with the AWS CLI | v6.0.0 |
+| [detect-private-key](https://github.com/pre-commit/pre-commit-hooks) | N/A | checks for the existence of private keys | v6.0.0 |
+| [end-of-file-fixer](https://github.com/pre-commit/pre-commit-hooks) | N/A | makes sure files end in a newline and only a newline | v6.0.0 |
+| [file-contents-sorter](https://github.com/pre-commit/pre-commit-hooks) | N/A | sort the lines in specified files (defaults to alphabetical) | v6.0.0 |
+| [fix-byte-order-marker](https://github.com/pre-commit/pre-commit-hooks) | N/A | removes UTF-8 byte order marker | v6.0.0 |
+| [forbid-submodules](https://github.com/pre-commit/pre-commit-hooks) | N/A | forbids any submodules in the repository | v6.0.0 |
+| [mixed-line-ending](https://github.com/pre-commit/pre-commit-hooks) | N/A | replaces or checks mixed line ending | v6.0.0 |
+| [trailing-whitespace](https://github.com/pre-commit/pre-commit-hooks) | N/A | trims trailing whitespace | v6.0.0 |
+| [codespell](https://github.com/codespell-project/codespell) | N/A | Check spelling with codespell | v2.4.1 |
+| [flake8](https://github.com/pycqa/flake8) | N/A | flake8 is a Python tool that glues together pycodestyle, pyflakes, mccabe, and third-party plugins to check the style and quality of some python code | 7.0.0 |
+| [markdownlint](https://github.com/igorshubovych/markdownlint-cli) | N/A | check Markdown files with markdownlint | v0.45.0 |
+| [yamllint](https://github.com/adrienverge/yamllint) | N/A | check YAML files with yamllint | v1.37.1 |

requirements-dev.txt

@@ -16,3 +16,4 @@
 # under the License.
 
 pre-commit
+pyyaml