Script to update the docs table

Makefile

@@ -26,6 +26,11 @@ check_doc_links: ## Check markdown files for invalid links
 	@python3 tools/python/verify_doc_links.py
 	@echo "$@: OK"
 
+.PHONY: update_doc_table
+update_doc_table: ## Check markdown files for invalid links
+	@python3 tools/python/update_doc_table.py
+	@echo "$@: OK"
+
 .PHONY: check_license
 check_license: ## Make sure source files have license header
 	@git grep -L "SPDX-License-Identifier: Apache-2.0" -- *.py *.yml *.yaml *.sh *.html *.js *.css *.ts *.tsx ':!*.bundle.js' | \

docs/README.md

@@ -1,12 +1,14 @@
-| Document                                                                                                     | Description   |
-| :-----------                                                                                                      | :------------- |
-| [import-assets.md](./import-assets.md)                           | Import a catalog of assets to an MLX instance |
-| [install-mlx-on-kind.md](./install-mlx-on-kind.md)               | Deploy MLX on [Kubernetes in Docker (KIND)](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)  |
-| [install-mlx-on-kubeflow.md](./install-mlx-on-kubeflow.md) | Deploy MLX on an existing Kubeflow cluster             |
-| [mlx-install-operator.md](./mlx-install-operator.md)             | Deploy MLX using [Kubeflow Operator](https://www.kubeflow.org/docs/distributions/operator/introduction/)  |
-| [mlx-install-with-kubeflow.md](./mlx-install-with-kubeflow.md)   | Deploy MLX on an existing Kubernetes or OpenShift cluster |
-| [mlx-read-only-deployment.md](./mlx-read-only-deployment.md)     | Deploy MLX in Read-Only Mode on an existing Kubernetes or OpenShift cluster |
-| [mlx-setup.md](./mlx-setup.md)                                   | Deploy MLX in single-user mode on an existing Kubernetes or OpenShift cluster |
-| [mlx-workshop.md](./mlx-workshop.md)                             | MLX Tutorial demonstrating data analysis, model training and deployment on Kubernetes |
-| [troubleshooting.md](./troubleshooting.md)                       | Common issues deploying MLX  |
-| [usage-steps.md](./usage-steps.md)                               | Navigation links to step-by-step usage tutorials |
+<!-- Do not edit. This file was generated by ./tools/python/update_doc_table.py (make update_doc_table) -->
+
+| Document | Description |
+| --- | --- |
+| [import-assets.md](./import-assets.md) | Import Data and AI Assets in MLX Catalog |
+| [install-mlx-on-kind.md](./install-mlx-on-kind.md) | Deploy MLX on KIND |
+| [install-mlx-on-kubeflow.md](./install-mlx-on-kubeflow.md) | Deploy MLX on an Existing Kubeflow Cluster |
+| [mlx-install-operator.md](./mlx-install-operator.md) | Install Operator Manually |
+| [mlx-install-with-kubeflow.md](./mlx-install-with-kubeflow.md) | MLX Deployment on Kubernetes or OpenShift (Asset Catalog and Execution Engine) |
+| [mlx-read-only-deployment.md](./mlx-read-only-deployment.md) | Deploy the MLX Read-Only mode on an Existing Kubernetes Cluster |
+| [mlx-setup.md](./mlx-setup.md) | Deploy MLX on an existing Kubernetes cluster |
+| [mlx-workshop.md](./mlx-workshop.md) | MLX Workshop |
+| [troubleshooting.md](./troubleshooting.md) | Troubleshooting |
+| [usage-steps.md](./usage-steps.md) | Usage Steps |

docs/mlx-read-only-deployment.md

@@ -1,4 +1,3 @@
-
 ## Deploy the MLX Read-Only mode on an Existing Kubernetes Cluster
 
 To deploy MLX in read-only mode on an existing Kubernetes cluster without Kubeflow, clone the MLX repo and apply the manifest using Kustomize:

tools/python/update_doc_table.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+
+# Copyright 2021 The MLX Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+    This script is used to (re)generate the /docs/README.md file with a table that describes the
+    purpose of each document. Run it from the project root folder via `make update_doc_table`.
+"""
+
+import itertools
+import re
+
+from glob import glob
+from os.path import abspath, dirname, split
+
+md_file_path_expressions = [
+    "/docs/*.md"
+]
+
+script_folder = abspath(dirname(__file__))
+project_root_dir = abspath(dirname(dirname(script_folder)))
+
+
+def find_md_files() -> [str]:
+
+    print("Checking for Markdown files here:\n")
+    for path_expr in md_file_path_expressions:
+        print("  " + path_expr.lstrip("/"))
+    print("")
+
+    md_files_list_of_lists = [glob(project_root_dir + path_expr, recursive=True)
+                              for path_expr in md_file_path_expressions]
+
+    return sorted(list(itertools.chain(*md_files_list_of_lists)))
+
+
+def get_header_from_md_file(md_file_path: str) -> [str]:
+
+    with open(md_file_path, "r") as f:
+        md_file_content = f.readline()
+
+    # remove "#" and newline character
+    header = re.sub(r"#+ *|\n", "", md_file_content)
+
+    # return description header
+    return header
+
+
+def update_doc_table() -> [str]:
+
+    # 1. find all relevant Markdown files
+    md_file_paths = find_md_files()
+
+    # 2. extract all descriptions using headers (first line) from files
+    descriptions = [
+        get_header_from_md_file(file)
+        for file in md_file_paths
+    ]
+
+    # 3. format filenames as Markdown hyperlinks: [name](url)
+    md_filenames = ["[" + split(file)[1] + "](./" + split(file)[1] + ")"
+                    for file in md_file_paths]
+
+    table = []
+    table.append(
+        "<!-- Do not edit. This file was generated by ./tools/python/update_doc_table.py (make update_doc_table) -->\n"
+        "\n"
+        "| Document | Description |\n"
+        "| --- | --- |"
+    )
+
+    for i in range(len(md_filenames)):
+        if("README.md" in md_filenames[i]):
+            continue
+        table.append(
+            f"| {md_filenames[i]} | {descriptions[i]} |"
+        )
+
+    f = open("./docs/README.md", "w")
+    f.write("\n".join(table))
+    f.close()
+
+
+if __name__ == '__main__':
+    update_doc_table()