[CI] pre-commit: auto create hook docs with Python

.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-hooks.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

@@ -29,10 +29,20 @@ repos:
     hooks:
       - id: identity
         name: run identity check
+        description: checks to see if your identity is set
       - id: check-hooks-apply
         name: run check hooks apply
+        description: makes sure all hooks apply to the repository
   - 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
       - id: prettier
         name: run prettier
         description: format files with prettier

pre-commit-hooks.md

@@ -0,0 +1,73 @@
+<!--
+ 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 | checks to see if your identity is set | N/A |
+| check-hooks-apply | N/A | makes sure all hooks apply to the repository | N/A |
+| create-pre-commit-docs | python | creates a Markdown file with information on the pre-commit hooks | N/A |
+| prettier | node | format files with prettier | N/A |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all .c files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all .h files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all Java files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all Markdown files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all Makefile files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all R files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all Scala files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all TOML files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all YAML files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all Python files | v1.5.5 |
+| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | add license for all other files | v1.5.5 |
+| [pyupgrade](https://github.com/asottile/pyupgrade) | N/A | N/A | v3.20.0 |
+| [black-jupyter](https://github.com/psf/black-pre-commit-mirror) | N/A | format Python files and Jupyter Notebooks with black | 25.1.0 |
+| [clang-format](https://github.com/pre-commit/mirrors-clang-format) | N/A | format C files with clang-format | v20.1.7 |
+| [bandit](https://github.com/PyCQA/bandit) | N/A | check Python code for security issues | 1.8.6 |
+| [codespell](https://github.com/codespell-project/codespell) | N/A | check spelling with codespell | v2.4.1 |
+| [gitleaks](https://github.com/gitleaks/gitleaks) | N/A | check for secrets with gitleaks | v8.27.2 |
+| [check-ast](https://github.com/pre-commit/pre-commit-hooks) | N/A | check Python files for syntax errors | v5.0.0 |
+| [check-builtin-literals](https://github.com/pre-commit/pre-commit-hooks) | N/A | check Python files for proper use of built-in literals | v5.0.0 |
+| [check-case-conflict](https://github.com/pre-commit/pre-commit-hooks) | N/A | check for case conflicts in file names | v5.0.0 |
+| [check-docstring-first](https://github.com/pre-commit/pre-commit-hooks) | N/A | check that docstrings are at the start of functions | v5.0.0 |
+| [check-executables-have-shebangs](https://github.com/pre-commit/pre-commit-hooks) | N/A | check that executable scripts have shebang lines | v5.0.0 |
+| [check-illegal-windows-names](https://github.com/pre-commit/pre-commit-hooks) | N/A | check for Windows-illegal file names | v5.0.0 |
+| [check-json](https://github.com/pre-commit/pre-commit-hooks) | N/A | check JSON files for syntax errors | v5.0.0 |
+| [check-merge-conflict](https://github.com/pre-commit/pre-commit-hooks) | N/A | check for merge conflict markers | v5.0.0 |
+| [check-shebang-scripts-are-executable](https://github.com/pre-commit/pre-commit-hooks) | N/A | check that scripts with shebangs are executable | v5.0.0 |
+| [check-toml](https://github.com/pre-commit/pre-commit-hooks) | N/A | check TOML files for syntax errors | v5.0.0 |
+| [check-vcs-permalinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [check-xml](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [check-yaml](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [debug-statements](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [destroyed-symlinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [detect-aws-credentials](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [detect-private-key](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [end-of-file-fixer](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [file-contents-sorter](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [fix-byte-order-marker](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [forbid-submodules](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [mixed-line-ending](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [name-tests-test](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [requirements-txt-fixer](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [trailing-whitespace](https://github.com/pre-commit/pre-commit-hooks) | N/A | N/A | v5.0.0 |
+| [markdownlint](https://github.com/igorshubovych/markdownlint-cli) | N/A | check Markdown files with markdownlint | v0.45.0 |
+| [shellcheck](https://github.com/shellcheck-py/shellcheck-py) | N/A | check Shell scripts with shellcheck | v0.10.0.1 |
+| [yamllint](https://github.com/adrienverge/yamllint) | N/A | check YAML files with yamllint | v1.37.1 |
+| [oxipng](https://github.com/shssoichiro/oxipng) | N/A | check PNG files with oxipng | v9.1.5 |

requirements-dev.txt

@@ -1 +1,2 @@
 pre-commit
+pyyaml