feat: add auto-generated CI documentation pre-commit hook (#2890)

# What does this PR do?
Our CI is entirely undocumented, this commit adds a README.md file with
a table of the current CI and what is does

---------

Signed-off-by: Nathan Weinberg <nweinber@redhat.com>

.github/workflows/README.md

@@ -0,0 +1,22 @@
+# Llama Stack CI
+
+Llama Stack uses GitHub Actions for Continous Integration (CI). Below is a table detailing what CI the project includes and the purpose.
+
+| Name | File | Purpose |
+| ---- | ---- | ------- |
+| Update Changelog | [changelog.yml](changelog.yml) | Creates PR for updating the CHANGELOG.md |
+| Coverage Badge | [coverage-badge.yml](coverage-badge.yml) | Creates PR for updating the code coverage badge |
+| Installer CI | [install-script-ci.yml](install-script-ci.yml) | Test the installation script |
+| Integration Auth Tests | [integration-auth-tests.yml](integration-auth-tests.yml) | Run the integration test suite with Kubernetes authentication |
+| SqlStore Integration Tests | [integration-sql-store-tests.yml](integration-sql-store-tests.yml) | Run the integration test suite with SqlStore |
+| Integration Tests | [integration-tests.yml](integration-tests.yml) | Run the integration test suite with Ollama |
+| Vector IO Integration Tests | [integration-vector-io-tests.yml](integration-vector-io-tests.yml) | Run the integration test suite with various VectorIO providers |
+| Pre-commit | [pre-commit.yml](pre-commit.yml) | Run pre-commit checks |
+| Test Llama Stack Build | [providers-build.yml](providers-build.yml) | Test llama stack build |
+| Python Package Build Test | [python-build-test.yml](python-build-test.yml) | Test building the llama-stack PyPI project |
+| Check semantic PR titles | [semantic-pr.yml](semantic-pr.yml) | Ensure that PR titles follow the conventional commit spec |
+| Close stale issues and PRs | [stale_bot.yml](stale_bot.yml) | Run the Stale Bot action |
+| Test External Providers Installed via Module | [test-external-provider-module.yml](test-external-provider-module.yml) | Test External Provider installation via Python module |
+| Test External API and Providers | [test-external.yml](test-external.yml) | Test the External API and Provider mechanisms |
+| Unit Tests | [unit-tests.yml](unit-tests.yml) | Run the unit test suite |
+| Update ReadTheDocs | [update-readthedocs.yml](update-readthedocs.yml) | Update the Llama Stack ReadTheDocs site |

.github/workflows/changelog.yml

@@ -1,5 +1,7 @@
 name: Update Changelog
 
+run-name: Creates PR for updating the CHANGELOG.md
+
 on:
   release:
     types: [published, unpublished, created, edited, deleted, released]

.github/workflows/coverage-badge.yml

@@ -1,5 +1,7 @@
 name: Coverage Badge
 
+run-name: Creates PR for updating the code coverage badge
+
 on:
   push:
     branches: [ main ]

.github/workflows/install-script-ci.yml

@@ -1,5 +1,7 @@
 name: Installer CI
 
+run-name: Test the installation script
+
 on:
   pull_request:
     paths:

.github/workflows/integration-auth-tests.yml

@@ -1,5 +1,7 @@
 name: Integration Auth Tests
 
+run-name: Run the integration test suite with Kubernetes authentication
+
 on:
   push:
     branches: [ main ]

.github/workflows/integration-sql-store-tests.yml

@@ -1,5 +1,7 @@
 name: SqlStore Integration Tests
 
+run-name: Run the integration test suite with SqlStore
+
 on:
   push:
     branches: [ main ]

.github/workflows/integration-tests.yml

@@ -1,5 +1,7 @@
 name: Integration Tests
 
+run-name: Run the integration test suite with Ollama
+
 on:
   push:
     branches: [ main ]

.github/workflows/integration-vector-io-tests.yml

@@ -1,5 +1,7 @@
 name: Vector IO Integration Tests
 
+run-name: Run the integration test suite with various VectorIO providers
+
 on:
   push:
     branches: [ main ]

.github/workflows/pre-commit.yml

@@ -1,5 +1,7 @@
 name: Pre-commit
 
+run-name: Run pre-commit checks
+
 on:
   pull_request:
   push:

.github/workflows/providers-build.yml

@@ -1,5 +1,7 @@
 name: Test Llama Stack Build
 
+run-name: Test llama stack build
+
 on:
   push:
     branches:

.github/workflows/python-build-test.yml

@@ -1,5 +1,7 @@
 name: Python Package Build Test
 
+run-name: Test building the llama-stack PyPI project
+
 on:
   push:
     branches:

.github/workflows/semantic-pr.yml

@@ -1,5 +1,7 @@
 name: Check semantic PR titles
 
+run-name: Ensure that PR titles follow the conventional commit spec
+
 on:
   pull_request_target:
     types:

.github/workflows/stale_bot.yml

@@ -1,5 +1,7 @@
 name: Close stale issues and PRs
 
+run-name: Run the Stale Bot action
+
 on:
   schedule:
     - cron: '0 0 * * *' # every day at midnight

.github/workflows/test-external-provider-module.yml

@@ -1,5 +1,7 @@
 name: Test External Providers Installed via Module
 
+run-name: Test External Provider installation via Python module
+
 on:
   push:
     branches: [ main ]

.github/workflows/test-external.yml

@@ -1,5 +1,7 @@
 name: Test External API and Providers
 
+run-name: Test the External API and Provider mechanisms
+
 on:
   push:
     branches: [ main ]

.github/workflows/unit-tests.yml

@@ -1,5 +1,7 @@
 name: Unit Tests
 
+run-name: Run the unit test suite
+
 on:
   push:
     branches: [ main ]

.github/workflows/update-readthedocs.yml

@@ -1,5 +1,7 @@
 name: Update ReadTheDocs
 
+run-name: Update the Llama Stack ReadTheDocs site
+
 on:
   workflow_dispatch:
     inputs:

.pre-commit-config.yaml

@@ -145,6 +145,15 @@ repos:
               echo;
               exit 1;
             } || true
+      - id: generate-ci-docs
+        name: Generate CI documentation
+        additional_dependencies:
+          - uv==0.7.8
+        entry: uv run ./scripts/gen-ci-docs.py
+        language: python
+        pass_filenames: false
+        require_serial: true
+        files: ^.github/workflows/.*$
 
 ci:
     autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

scripts/gen-ci-docs.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).parent.parent
+
+
+def parse_workflow_file(file_path):
+    """Parse a workflow YAML file and extract name and run-name."""
+    try:
+        with open(file_path, encoding="utf-8") as f:
+            content = yaml.safe_load(f)
+
+        name = content["name"]
+        run_name = content["run-name"]
+
+        return name, run_name
+    except Exception as e:
+        raise Exception(f"Error parsing {file_path}") from e
+
+
+def generate_ci_docs():
+    """Generate the CI documentation README.md file."""
+
+    # Define paths
+    workflows_dir = REPO_ROOT / ".github/workflows"
+    readme_path = workflows_dir / "README.md"
+
+    # Header section to preserve
+    header = """# Llama Stack CI
+
+Llama Stack uses GitHub Actions for Continous Integration (CI). Below is a table detailing what CI the project includes and the purpose.
+
+| Name | File | Purpose |
+| ---- | ---- | ------- |
+"""
+
+    # Get all .yml files in workflows directory
+    yml_files = []
+    for file_path in workflows_dir.glob("*.yml"):
+        yml_files.append(file_path)
+
+    # Sort files alphabetically for consistent output
+    yml_files.sort(key=lambda x: x.name)
+
+    # Generate table rows
+    table_rows = []
+    for file_path in yml_files:
+        name, run_name = parse_workflow_file(file_path)
+        filename = file_path.name
+
+        # Create markdown link in the format [filename.yml](filename.yml)
+        file_link = f"[{filename}]({filename})"
+
+        # Create table row
+        row = f"| {name} | {file_link} | {run_name} |"
+        table_rows.append(row)
+
+    # Combine header and table rows
+    content = header + "\n".join(table_rows) + "\n"
+
+    # Write to README.md
+    with open(readme_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    print(f"Generated {readme_path} with {len(table_rows)} workflow entries")
+
+
+if __name__ == "__main__":
+    generate_ci_docs()