ci(docs): add automatic doc generation to pre-commit (#35)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* Documentation
* Updated branding to “Open Data Hub Llama Stack” and expanded build
instructions with clear prerequisites and step-by-step guidance.
* Added a distribution overview including a generated table mapping APIs
to their providers.
* Clarified how to edit the Containerfile template and reiterated not to
modify the generated file directly.

* Chores
* Added a pre-commit check to automatically generate distribution
documentation from the configuration.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: nathan-weinberg

.pre-commit-config.yaml

@@ -57,3 +57,13 @@ repos:
         files: ^distribution/.*$
         additional_dependencies:
           - llama-stack==0.2.21
+
+      - id: doc-gen
+        name: Distribution Documentation
+        entry: ./scripts/gen_distro_docs.py
+        language: python
+        pass_filenames: false
+        require_serial: true
+        files: ^distribution/run\.yaml$
+        additional_dependencies:
+          - pyyaml==6.0.2

README.md

@@ -1,14 +1,18 @@
-# Red Hat Distribution Build Instructions
+# Open Data Hub Llama Stack Distribution
 
-This directory contains the necessary files to build a Red Hat compatible container image for the llama-stack.
+This directory contains the necessary files to build an Open Data Hub-compatible container image for [Llama Stack](https://github.com/llamastack/llama-stack).
 
-## Prerequisites
+To learn more about the distribution image content, see the [README](distribution/README.md) in the `distribution/` directory.
+
+## Build Instructions
+
+### Prerequisites
 
 - Python >=3.11
 - `llama` CLI tool installed: `pip install llama-stack`
 - Podman or Docker installed
 
-## Generating the Containerfile
+### Generating the Containerfile
 
 The Containerfile is auto-generated from a template. To generate it:
 
@@ -23,26 +27,26 @@ This will:
 - Generate dependencies using `llama stack build`
 - Create a new `Containerfile` with the required dependencies
 
-## Editing the Containerfile
+### Editing the Containerfile
 
 The Containerfile is auto-generated from a template. To edit it, you can modify the template in `distribution/Containerfile.in` and run the build script again.
 NEVER edit the generated `Containerfile` manually.
 
-## Building the Container Image
+### Building the Container Image
 
 Once the Containerfile is generated, you can build the image using either Podman or Docker:
 
-### Using Podman build image for x86_64
+#### Using Podman build image for x86_64
 
 ```bash
 podman build --platform linux/amd64 -f distribution/Containerfile -t rh .
 ```
 
-## Notes
+### Notes
 
 - The generated Containerfile should not be modified manually as it will be overwritten the next time you run the build script
 
-## Push the image to a registry
+### Push the image to a registry
 
 ```bash
 podman push <build-ID> quay.io/opendatahub/llama-stack:rh-distribution

distribution/README.md

@@ -0,0 +1,30 @@
+<!-- This file is automatically generated by scripts/gen_distro_doc.py - do not update manually -->
+
+# Open Data Hub Llama Stack Distribution Image
+
+This image contains the official Open Data Hub Llama Stack distribution, with all the packages and configuration needed to run a Llama Stack server in a containerized environment.
+
+You can see an overview of the APIs and Providers the image ships with in the table below.
+
+| API | Provider |
+|-----|----------|
+| agents | inline::meta-reference |
+| datasetio | inline::localfs |
+| datasetio | remote::huggingface |
+| eval | remote::trustyai_lmeval |
+| files | inline::localfs |
+| inference | inline::sentence-transformers |
+| inference | remote::bedrock |
+| inference | remote::vllm |
+| inference | remote::watsonx |
+| safety | remote::trustyai_fms |
+| scoring | inline::basic |
+| scoring | inline::braintrust |
+| scoring | inline::llm-as-judge |
+| telemetry | inline::meta-reference |
+| tool_runtime | inline::rag-runtime |
+| tool_runtime | remote::brave-search |
+| tool_runtime | remote::model-context-protocol |
+| tool_runtime | remote::tavily-search |
+| vector_io | inline::milvus |
+| vector_io | remote::milvus |

scripts/gen_distro_docs.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+
+import yaml
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).parent.parent
+
+
+def gen_distro_table(providers_data):
+    # Start with table header
+    table_lines = ["| API | Provider |", "|-----|----------|"]
+
+    # Create a list to collect all API-Provider pairs for sorting
+    api_provider_pairs = []
+
+    # Iterate through each API type and its providers
+    for api_name, provider_list in providers_data.items():
+        if isinstance(provider_list, list):
+            for provider in provider_list:
+                if isinstance(provider, dict) and "provider_type" in provider:
+                    provider_type = provider["provider_type"]
+                    api_provider_pairs.append((api_name, provider_type))
+
+    # Sort first by API name, then by provider type
+    api_provider_pairs.sort(key=lambda x: (x[0], x[1]))
+
+    # Add sorted pairs to table
+    for api_name, provider_type in api_provider_pairs:
+        table_lines.append(f"| {api_name} | {provider_type} |")
+
+    return "\n".join(table_lines)
+
+
+def gen_distro_docs():
+    # define distro run.yaml and README.md paths
+    run_yaml_path = REPO_ROOT / "distribution" / "run.yaml"
+    readme_path = REPO_ROOT / "distribution" / "README.md"
+
+    # Check if run.yaml exists
+    if not run_yaml_path.exists():
+        print(f"Error: {run_yaml_path} not found")
+        return 1
+
+    # header section
+    header = """<!-- This file is automatically generated by scripts/gen_distro_doc.py - do not update manually -->
+
+# Open Data Hub Llama Stack Distribution Image
+
+This image contains the official Open Data Hub Llama Stack distribution, with all the packages and configuration needed to run a Llama Stack server in a containerized environment.
+
+You can see an overview of the APIs and Providers the image ships with in the table below.
+
+"""
+
+    try:
+        # Load the run.yaml data
+        with open(run_yaml_path, "r") as file:
+            run_yaml_data = yaml.safe_load(file)
+
+        # Extract providers section
+        providers = run_yaml_data.get("providers", {})
+
+        if not providers:
+            print("Error: No providers found in run.yaml")
+            return 1
+
+        # Generate the Markdown table
+        table_content = gen_distro_table(providers)
+
+        # Write to README.md
+        with open(readme_path, "w") as readme_file:
+            readme_file.write(header + table_content + "\n")
+
+        print(f"Successfully generated {readme_path}")
+        print(
+            "Ensure you have checked-in any changes to the README to git, or the pre-commit check using this script will fail"
+        )
+        return 0
+
+    except Exception as e:
+        print(f"Error: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    exit(gen_distro_docs())