diff --git a/Makefile b/Makefile index 51ab5087..804bdded 100644 --- a/Makefile +++ b/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' | \ diff --git a/docs/README.md b/docs/README.md index d33951ad..ad2a30ad 100644 --- a/docs/README.md +++ b/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 | \ No newline at end of file + + +| 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 | diff --git a/docs/mlx-read-only-deployment.md b/docs/mlx-read-only-deployment.md index 55692aa5..38780ed3 100644 --- a/docs/mlx-read-only-deployment.md +++ b/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: diff --git a/tools/python/update_doc_table.py b/tools/python/update_doc_table.py new file mode 100755 index 00000000..710cb2f6 --- /dev/null +++ b/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( + "\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()