From e616d3584737686f6d221ce3f21c67b98a936827 Mon Sep 17 00:00:00 2001
From: Kun Lin <81014421+klhhhhh@users.noreply.github.com>
Date: Wed, 4 Feb 2026 22:59:40 -0500
Subject: [PATCH] Support Markdown/Notebook-Friendly Documentation Export for
 Downstream Integration(convert rat files to md files and save) (#18278)

---
 docs/Makefile | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index a15ce24d9..716160e56 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -44,17 +44,22 @@ markdown:
 	echo "Exporting docs to Markdown..."; \
 	mkdir -p "$(BUILDDIR)/html/markdown"; \
 	\
-	# 1) Copy .md and .rst files under subdirectories only (exclude root-level files) \
-	find $(SOURCEDIR) -mindepth 2 -path "*/_build/*" -prune -o \( -name "*.md" -o -name "*.rst" \) -print0 | \
+	# 1) Copy .md and .rst files as-is; additionally convert .rst -> .md \
+	find $(SOURCEDIR) -path "*/_build/*" -prune -o \( -name "*.md" -o -name "*.rst" \) -print0 | \
 		parallel -0 -j3 --halt soon,fail=1 ' \
 		SRC="{}"; \
 		REL_DIR=$$(dirname "$$SRC"); \
 		OUT_DIR="$(BUILDDIR)/html/markdown/$$REL_DIR"; \
 		mkdir -p "$$OUT_DIR"; \
 		cp -f "$$SRC" "$$OUT_DIR/"; \
+		case "$$SRC" in \
+		  *.rst) \
+			BASE=$$(basename "$$SRC" .rst); \
+			pandoc -f rst -t gfm "$$SRC" -o "$$OUT_DIR/$$BASE.md" ;; \
+		esac \
 		' || exit 1; \
 	\
-	# 2) Convert .ipynb -> .md (all notebooks, including root if any) \
+	# 2) Convert .ipynb -> .md \
 	find $(SOURCEDIR) -path "*/_build/*" -prune -o -name "*.ipynb" -print0 | \
 		parallel -0 -j3 --halt soon,fail=1 ' \
 		NB_SRC="{}"; \
@@ -72,6 +77,7 @@ markdown:
 	echo "Markdown artifacts written to: $(BUILDDIR)/html/markdown"
 
 
+
 # Serve documentation with auto-build and live reload
 serve:
 	@echo "Starting auto-build server at http://0.0.0.0:$(PORT)"