Add custom edit URLs to generated website pages. (iree-org#15605)

The MLIR dialect reference pages at
https://iree.dev/reference/mlir-dialects/ are generated from a mix of
.td (tablegen) files. This fixes the "edit this page" links for those
pages to point at valid source locations


![image](https://github.com/openxla/iree/assets/4010439/a1129072-5371-4555-87ac-6c80ec6fe07d)

For example, https://iree.dev/reference/mlir-dialects/HAL/ now points to
https://github.com/openxla/iree/tree/main/compiler/src/iree/compiler/Dialect/HAL/IR
instead of
https://github.com/openxla/iree/blob/main/docs/website/docs/reference/mlir-dialects/HAL.md
(which does not exist)

docs/website/custom_edit_url.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+# Copyright 2023 The IREE Authors
+#
+# Licensed under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""Custom edit URL plugin for mkdocs.
+
+MkDocs can create links to view/edit the source of a website page in the
+associated source location (e.g. GitHub repository).
+
+* https://www.mkdocs.org/user-guide/configuration/#edit_uri
+* https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions
+
+For markdown files in the documentation folder, this is a straightforward
+process, taking the relative path and appending it to the source location:
+  /repo_root/docs/section/page.md -->
+  https://github.com/[org]/[repo]/blob/main/docs/section/page.md
+
+For generated files, the inferred URL does not match the actual source:
+  /repo_root/src/file.cc -->
+  /repo_root/docs/gen/file.md -->
+  [broken link] https://github.com/[org]/[repo]/blob/main/docs/gen/file.md
+
+This plugin allows for pages to explicitly specify their source URL via
+markdown frontmatter.
+
+References:
+* https://github.com/renovatebot/renovatebot.github.io/pull/187
+* https://github.com/mkdocs/mkdocs/discussions/2757
+
+Usage:
+
+1. Add a hook to mkdocs.yml by following
+    https://www.mkdocs.org/user-guide/configuration/#hooks
+
+2. Add frontmatter to any pages you want to customize:
+
+  ---
+  custom_edit_url: [full hyperlink to the source location, e.g. https://github.com/...]
+  ---
+"""
+
+
+def on_page_context(context, page, config, **kwargs):
+    if "custom_edit_url" in page.meta:
+        page.edit_url = page.meta["custom_edit_url"]
+    return context

docs/website/docs/reference/mlir-dialects/index.md

@@ -41,5 +41,6 @@ Dialect                             | Description
 ------------------------------------| -----------
 [IREEInput](./IREEInput.md)         | Structural ops legal as input to IREE's compiler
 [IREELinalgExt](./IREELinalgExt.md) | Extensions to the Linalg dialect for specific operations
+[IREEVectorExt](./IREEVectorExt.md) | Extensions to the Vector dialect for specific operations
 
 [^1]: Hardware Abstraction Layer

docs/website/generate_extra_files.sh

@@ -57,6 +57,7 @@ done
 # Rename iree-dialect files.
 mv "${BUILD_DOCS_PROCESSED_DIR}/InputOps.md" "${BUILD_DOCS_PROCESSED_DIR}/IREEInput.md"
 mv "${BUILD_DOCS_PROCESSED_DIR}/LinalgExtOps.md" "${BUILD_DOCS_PROCESSED_DIR}/IREELinalgExt.md"
+mv "${BUILD_DOCS_PROCESSED_DIR}/VectorExtOps.md" "${BUILD_DOCS_PROCESSED_DIR}/IREEVectorExt.md"
 # mv "${BUILD_DOCS_PROCESSED_DIR}/StructuredTransformOpsExt.md" "${BUILD_DOCS_PROCESSED_DIR}/IREEStructuredTransformExt.md"
 
 # Postprocess the dialect docs (e.g. making tweaks to the markdown source).

docs/website/mkdocs.yml

@@ -163,6 +163,7 @@ nav:
           - "Public dialects":
               - IREEInput: "reference/mlir-dialects/IREEInput.md"
               - IREELinalgExt: "reference/mlir-dialects/IREELinalgExt.md"
+              - IREEVectorExt: "reference/mlir-dialects/IREEVectorExt.md"
       - "Other topics":
           - Glossary: "reference/glossary.md"
           - Optimization options: "reference/optimization-options.md"
@@ -206,6 +207,11 @@ nav:
       - "Blog":
           - "community/blog/index.md"
       - "community/tags.md"
+
+# https://www.mkdocs.org/user-guide/configuration/#hooks
+hooks:
+  - custom_edit_url.py
+
 plugins:
   # https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/
   - blog:

docs/website/postprocess_dialect_docs.py

@@ -18,6 +18,7 @@
 
 import argparse
 import fileinput
+import os
 import pathlib
 import re
 
@@ -64,7 +65,40 @@ def main(args):
 
             print(line, end="")
 
-    # TODO(scotttodd): replace [TOC] with \n[TOC] as needed (transform ops)
+    # Add explicit custom_edit_url links as these markdown files were generated
+    # from other source files.
+    dialect_sources_map = {
+        "Check.md": "compiler/src/iree/compiler/Modules/Check/IR",
+        "Flow.md": "compiler/src/iree/compiler/Dialect/Flow/IR",
+        "HAL.md": "compiler/src/iree/compiler/Dialect/HAL/IR",
+        "HALInline.md": "compiler/src/iree/compiler/Modules/HAL/Inline/IR",
+        "HALLoader.md": "compiler/src/iree/compiler/Modules/HAL/Loader/IR",
+        "IOParameters.md": "compiler/src/iree/compiler/Modules/IO/Parameters/IR",
+        "IREEInput.md": "llvm-external-projects/iree-dialects/include/iree-dialects/Dialect/Input",
+        "IREELinalgExt.md": "llvm-external-projects/iree-dialects/include/iree-dialects/Dialect/LinalgExt/IR",
+        "IREEVectorExt.md": "llvm-external-projects/iree-dialects/include/iree-dialects/Dialect/VectorExt/IR",
+        "Stream.md": "compiler/src/iree/compiler/Dialect/Stream/IR",
+        "Util.md": "compiler/src/iree/compiler/Dialect/Util/IR",
+        "VM.md": "compiler/src/iree/compiler/Dialect/VM/IR",
+        "VMVX.md": "compiler/src/iree/compiler/Dialect/VMVX/IR",
+    }
+    base_url = "https://github.com/openxla/iree/tree/main/"
+    for file in files:
+        filename = pathlib.Path(file).name
+        relative_path = dialect_sources_map.get(filename, None)
+        if not relative_path:
+            print("Warning: missing dialect source path for '%s'" % filename)
+            continue
+
+        full_url = base_url + relative_path
+        with open(file, "r+") as f:
+            content = f.read()
+            f.seek(0, 0)
+            frontmatter = f"""---
+custom_edit_url: {full_url}
+---
+"""
+            f.write(frontmatter + os.linesep + content)
 
 
 def parse_arguments():