chore: update documentation, add pre-commit workflow

.github/workflows/pr-title-validation.yml

@@ -2,15 +2,13 @@ name: PR Validation
 
 on:
   pull_request:
-    branches: [ "main" ]
-  pull_request_target:
     types: [opened, synchronize, reopened, edited]
     branches: [ "main" ]
   merge_group:
     types: [checks_requested]
+
 permissions:
-  contents: read
-  pull-requests: write
+  contents: read  # Only read access needed for title validation
 
 jobs:
   validate:

.github/workflows/pre-commit.yml

@@ -0,0 +1,136 @@
+name: Pre-commit Checks
+
+# ============================================================================
+# WORKFLOW: PRE-COMMIT VALIDATION
+# ============================================================================
+#
+# This workflow runs all pre-commit hooks configured in .pre-commit-config.yaml
+# to validate PRs. This ensures that external contributors who may not have
+# pre-commit hooks installed locally still get the same validation feedback.
+#
+# CHECKS PERFORMED:
+# -----------------
+# All hooks from .pre-commit-config.yaml including:
+# - Documentation generation and validation (README.md + role READMEs)
+# - Markdown linting (markdownlint-cli2)
+# - Ansible linting (ansible-lint)
+# - Secret scanning (gitleaks)
+# - Merge conflict detection
+# - Trailing whitespace
+# - No direct commits to main branch
+# - Other standard pre-commit hooks
+#
+# DESIGN RATIONALE:
+# -----------------
+# Uses pull_request event for BOTH internal and external PRs because:
+# 1. Pre-commit hooks are READ-ONLY operations (no secrets needed)
+# 2. No write permissions required (workflow just fails the check)
+# 3. Provides immediate feedback to external contributors (no approval gate)
+# 4. Simpler than duplicating logic in custom CI steps
+#
+# SECURITY:
+# ---------
+# Safe for external PRs because:
+# - No repository secrets accessed
+# - Only read permissions (contents: read)
+# - Runs same validations as local pre-commit hooks
+# - Workflow failure is the feedback mechanism
+#
+# ============================================================================
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: ["main"]
+
+permissions:
+  contents: read  # Only read access needed for checkout and validation
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('requirements-ci.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          # Install pre-commit and CI dependencies
+          pip install pre-commit
+          pip install -r requirements-ci.txt
+
+      - name: Cache pre-commit environments
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+          restore-keys: |
+            pre-commit-${{ runner.os }}-
+
+      - name: Run pre-commit hooks
+        run: |
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          echo "🔍 Running pre-commit hooks (skipping ansible-lint)"
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          echo ""
+          echo "Note: ansible-lint is skipped in this workflow because it requires"
+          echo "      the collection to be built and installed with all dependencies."
+          echo "      It runs in the main CI workflow with proper setup."
+          echo ""
+
+          # Run pre-commit hooks, skipping ansible-lint
+          # ansible-lint is skipped because:
+          # - It requires the collection to be built and installed
+          # - It needs external collection dependencies
+          # - It's already run in the main CI workflow with proper setup
+          #
+          # This workflow focuses on quick, local-friendly checks:
+          # - Documentation generation and validation
+          # - Markdown linting
+          # - Secret scanning (gitleaks)
+          # - Trailing whitespace, merge conflicts, etc.
+
+          if SKIP=ansible-lint pre-commit run --all-files --show-diff-on-failure --color=always; then
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "✅ All pre-commit checks passed!"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            exit 0
+          else
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "❌ Pre-commit checks failed!"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo ""
+            echo "📝 How to fix:"
+            echo ""
+            echo "1. Install pre-commit hooks locally:"
+            echo "   pre-commit install"
+            echo ""
+            echo "2. Run pre-commit on all files:"
+            echo "   pre-commit run --all-files"
+            echo ""
+            echo "3. Fix any issues reported above"
+            echo ""
+            echo "4. Commit and push your changes"
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "💡 Tip: Installing pre-commit hooks locally will catch these"
+            echo "   issues before you push, providing faster feedback!"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo ""
+            exit 1
+          fi

.markdownlint-cli2.yaml

@@ -32,8 +32,7 @@ config:
   ol-prefix: false                  # MD029
   reference-links-images: false     # MD052
   table-column-style: false         # MD060
-  ul-style:                         # MD004
-    style: "asterisk"
+  ul-style: false                   # MD004
 
   # Keep this item last due to length
   proper-names: false

.pre-commit-config.yaml

@@ -35,16 +35,37 @@ repos:
     hooks:
       - id: ansible-lint
         additional_dependencies:
-        - ansible-core==2.20.0
-        - distlib
+          - ansible-core==2.20.0
+          - distlib
         stages: [pre-commit]
         pass_filenames: false
         always_run: true
         entry: "ansible-lint"
-        args: ["-c", ".ansible-lint"]
+        args: ["-c", ".ansible-lint", "--strict"]
 
   - repo: https://github.com/gitleaks/gitleaks
     rev: v8.30.0
     hooks:
       - id: gitleaks
+
+  # Documentation validation
+  # Ensures generated documentation (README.md and role READMEs) are up-to-date
+  - repo: local
+    hooks:
+      - id: update-documentation
+        name: Generate documentation
+        entry: bash scripts/update-documentation.sh
+        language: system
+        pass_filenames: false
+        always_run: true
+        verbose: true
+        description: Regenerates README.md and role READMEs using docsible
+
+      - id: check-documentation
+        name: Verify documentation is committed
+        entry: bash scripts/check-documentation.sh
+        language: system
+        pass_filenames: false
+        always_run: true
+        description: Checks that generated documentation has no uncommitted changes
 ...

README.md

@@ -5,44 +5,62 @@
 [![Semantic Versioning](https://img.shields.io/badge/semver-2.0.0-blue?style=flat-square)](https://semver.org/)
 [![License](https://img.shields.io/github/license/redhat-cop/openshift_virtualization_migration?style=flat-square)](LICENSE)
 
-## Table of Contents
-
-* [Description](#description)
-* [Requirements](#requirements)
-* [Installation](#installation)
-* [Documentation](#documentation)
-    * [Contributing](CONTRIBUTING.md)
-    * [Disconnected Environment](docs/disconnected_environment_guide.md)
-    * [Secure Credential Management](docs/secure_credential_management.md)
-    * [Secure Credential Practices](docs/secure_credential_practices.md)
-* [Roles](#roles)
-    * [aap_deploy](roles/aap_deploy/README.md)
-    * [aap_machine_credentials](roles/aap_machine_credentials/README.md)
-    * [aap_seed](roles/aap_seed/README.md)
-    * [bootstrap](roles/bootstrap/README.md)
-    * [create_mf_aap_token](roles/create_mf_aap_token/README.md)
-    * [mtv_management](roles/mtv_management/README.md)
-    * [mtv_migrate](roles/mtv_migrate/README.md)
-    * [network_mgmt](roles/network_mgmt/README.md)
-    * [operator_management](roles/operator_management/README.md)
-    * [validate_migration](roles/validate_migration/README.md)
-    * [vm_backup_restore](roles/vm_backup_restore/README.md)
-    * [vm_collect](roles/vm_collect/README.md)
-    * [vm_hot_plug](roles/vm_hot_plug/README.md)
-    * [vm_lifecycle](roles/vm_lifecycle/README.md)
-    * [vm_mac_address](roles/vm_mac_address/README.md)
-    * [vm_networking](roles/vm_networking/README.md)
-    * [vm_patching](roles/vm_patching/README.md)
-    * [vm_ssh](roles/vm_ssh/README.md)
-* [Use Cases](#use-cases)
-* [Testing](#testing)
-* [Release Notes](CHANGELOG.md)
-* [License](#license)
+<!--TOC-->
+
+- [Ansible for OpenShift Virtualization Migration](#ansible-for-openshift-virtualization-migration)
+  - [Description](#description)
+  - [Documentation](#documentation)
+  - [Release Notes](#release-notes)
+  - [Roles](#roles)
+  - [Requirements](#requirements)
+  - [Installation](#installation)
+  - [Use Cases](#use-cases)
+  - [Testing](#testing)
+  - [Support](#support)
+  - [License](#license)
+
+<!--TOC-->
 
 ## Description
 
 This collection enables the migration journey of Virtual Machine (VM) workloads from existing hypervisors to Red Hat OpenShift Virtualization using Ansible Automation Platform. Additionally it provides content for the management and maintenance of VM workloads within Red Hat OpenShift Virtualization.
 
+## Documentation
+
+* [Contributing Guide](CONTRIBUTING.md)
+* [Disconnected Environment Setup](docs/disconnected_environment_guide.md)
+* [Secure Credential Management](docs/secure_credential_management.md)
+* [Secure Credential Practices](docs/secure_credential_practices.md)
+
+## Release Notes
+
+See [CHANGELOG.md](CHANGELOG.md) for release history and changes.
+
+## Roles
+
+This collection includes the following roles for managing OpenShift Virtualization migrations:
+
+<!--ROLES_LIST_START-->
+* [aap_deploy](roles/aap_deploy/README.md) - Deploys an instance of Ansible Automation Platform.
+* [aap_machine_credentials](roles/aap_machine_credentials/README.md) - Management of Machine Credentials.
+* [aap_seed](roles/aap_seed/README.md) - Populates an Ansible Automation Platform instance.
+* [bootstrap](roles/bootstrap/README.md) - Initialization of the Ansible for OpenShift Virtualization Migration environment.
+* [create_mf_aap_token](roles/create_mf_aap_token/README.md) - create_mf_aap_token
+* [mtv_management](roles/mtv_management/README.md) - Management of the Migration Toolkit for Virtualization (MTV).
+* [mtv_migrate](roles/mtv_migrate/README.md) - Migration of Virtual Machines from Source to Destination.
+* [network_mgmt](roles/network_mgmt/README.md) - Management of network related components.
+* [operator_management](roles/operator_management/README.md) - Management of OpenShift Operators.
+* [validate_migration](roles/validate_migration/README.md) - Verification of an Ansible for OpenShift Virtualization Migration environment.
+* [vm_backup_restore](roles/vm_backup_restore/README.md) - Virtual Machine backup and restore capabilities.
+* [vm_collect](roles/vm_collect/README.md) - Collection of Migration Toolkit for Virtualization inventory information.
+* [vm_hot_plug](roles/vm_hot_plug/README.md) - Hot Plug Virtual Machine resources.
+* [vm_lifecycle](roles/vm_lifecycle/README.md) - Management of the lifecycle activities of Virtual Machines.
+* [vm_mac_address](roles/vm_mac_address/README.md) - Management of Virtual Machine MAC Addresses.
+* [vm_networking](roles/vm_networking/README.md) - Management of Virtual Machine networking.
+* [vm_patching](roles/vm_patching/README.md) - Patching related activities for Virtual Machines.
+* [vm_ssh](roles/vm_ssh/README.md) - Management of SSH keys for Virtual Machines in OpenShift.
+<!--ROLES_LIST_END-->
+
 ## Requirements
 
 The following Ansible Collections are required:

requirements-ci.txt

@@ -3,3 +3,4 @@ distlib==0.4.0
 antsibull-changelog==0.35.0
 docsible==0.8.0
 python-semantic-release==10.5.3
+md-toc>=9.0.0