From 1ea80a3f82bf29e0ac1baf0f5cc53fefdfa0cda2 Mon Sep 17 00:00:00 2001
From: Viraj Bhartiya <vlbhartiya@gmail.com>
Date: Fri, 15 Nov 2024 01:47:18 +0530
Subject: [PATCH] feat: add workflow to test readme generation (#6359)

# Description

Created a workflow to search for README.docify.md in the repo, and run
cargo build --features generate-readme in the dir of the file (assuming
it is related to a crate). If the git diff shows some output for the
README.md, then the file update wasn't pushed on the branch, and the
workflow fails.
Closes #6331

## Integration

Downstream projects that want to adopt this README checking workflow
should:

1. Copy the `.github/workflows/readme-check.yml` file to their
repository
2. Ensure any `README.docify.md` files in their project follow the
expected format
3. Implement the `generate-readme` feature flag in their Cargo.toml if
not already present

## Review Notes

This PR adds a GitHub Actions workflow that automatically verifies
README.md files are up-to-date with their corresponding README.docify.md
sources. Key implementation details:

- The workflow runs on both PRs and pushes to main
- It finds all `README.docify.md` files recursively in the repository
- For each file found:
- Builds the project with `--features generate-readme` in that directory
  - Checks if the README.md has any uncommitted changes
  - Fails if any README.md is out of sync

---------

Co-authored-by: Alexander Samusev <41779041+alvicsam@users.noreply.github.com>
Co-authored-by: Iulian Barbu <14218860+iulianbarbu@users.noreply.github.com>
---
 .../check-missing-readme-generation.sh        | 36 +++++++++++++++++++
 .github/workflows/checks-quick.yml            | 28 ++++++++++++++-
 2 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100755 .github/scripts/check-missing-readme-generation.sh

diff --git a/.github/scripts/check-missing-readme-generation.sh b/.github/scripts/check-missing-readme-generation.sh
new file mode 100755
index 000000000000..13f2b6a7cb28
--- /dev/null
+++ b/.github/scripts/check-missing-readme-generation.sh
@@ -0,0 +1,36 @@
+#!/bin/bash
+echo "Running script relative to `pwd`"
+# Find all README.docify.md files
+DOCIFY_FILES=$(find . -name "README.docify.md")
+
+# Initialize a variable to track directories needing README regeneration
+NEED_REGENERATION=""
+
+for file in $DOCIFY_FILES; do
+  echo "Processing $file"
+  
+  # Get the directory containing the docify file
+  DIR=$(dirname "$file")
+  
+  # Go to the directory and run cargo build
+  cd "$DIR"
+  cargo check --features generate-readme || { echo "Readme generation for $DIR failed. Ensure the crate compiles successfully and has a `generate-readme` feature which guards markdown compilation in the crate as follows: https://docs.rs/docify/latest/docify/macro.compile_markdown.html#conventions." && exit 1; }
+  
+  # Check if README.md has any uncommitted changes
+  git diff --exit-code README.md
+  
+  if [ $? -ne 0 ]; then
+    echo "Error: Found uncommitted changes in $DIR/README.md"
+    NEED_REGENERATION="$NEED_REGENERATION $DIR"
+  fi
+  
+  # Return to the original directory
+  cd - > /dev/null
+done
+
+# Check if any directories need README regeneration
+if [ -n "$NEED_REGENERATION" ]; then
+  echo "The following directories need README regeneration:"
+  echo "$NEED_REGENERATION"
+  exit 1
+fi
\ No newline at end of file
diff --git a/.github/workflows/checks-quick.yml b/.github/workflows/checks-quick.yml
index 36deba7dfb78..28f5bf932e2c 100644
--- a/.github/workflows/checks-quick.yml
+++ b/.github/workflows/checks-quick.yml
@@ -15,7 +15,6 @@ concurrency:
 permissions: {}
 
 jobs:
-
   preflight:
     uses: ./.github/workflows/reusable-preflight.yml
 
@@ -172,6 +171,32 @@ jobs:
         env:
           ASSERT_REGEX: "FAIL-CI"
           GIT_DEPTH: 1
+  check-readme:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install prerequisites
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y protobuf-compiler
+
+      - name: Set rust version from env file
+        run: |
+          RUST_VERSION=$(cat .github/env | sed -E 's/.*ci-unified:([^-]+)-([^-]+).*/\2/')
+          echo $RUST_VERSION
+          echo "RUST_VERSION=${RUST_VERSION}" >> $GITHUB_ENV
+
+      - name: Install Rust
+        uses: actions-rust-lang/setup-rust-toolchain@11df97af8e8102fd60b60a77dfbf58d40cd843b8 # v1.10.1
+        with:
+          cache: false
+          toolchain: ${{ env.RUST_VERSION }}
+          components: cargo, clippy, rust-docs, rust-src, rustfmt, rustc, rust-std
+
+      - name: Find README.docify.md files and check generated READMEs
+        run: .github/scripts/check-missing-readme-generation.sh
 
   confirm-required-checks-quick-jobs-passed:
     runs-on: ubuntu-latest
@@ -187,6 +212,7 @@ jobs:
       - check-markdown
       - check-umbrella
       - check-fail-ci
+      - check-readme
     if: always() && !cancelled()
     steps:
       - run: |