From c42a9faad8d84f7bd05457d5f8e1fe45d6eecfa2 Mon Sep 17 00:00:00 2001
From: Yong He <yonghe@outlook.com>
Date: Tue, 8 Oct 2024 13:29:57 -0700
Subject: Overhaul docgen tool and setup CI to generate stdlib reference.
 (#5232)

* Overhaul docgen tool and setup CI to generate stdlib reference.

* Fix build error.

* Write parsed doc for all decls.

* fix.

* fix callout.

* Fix.

* Fix comment.

* Fix.

* Delete obsolete doc tests.

* Fix.

* Categorize functions and types.

* Fix CI.

* Update comments.
---
 docs/build_reference.ps1 | 51 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 docs/build_reference.ps1

(limited to 'docs/build_reference.ps1')

diff --git a/docs/build_reference.ps1 b/docs/build_reference.ps1
new file mode 100644
index 000000000..d08d7b30d
--- /dev/null
+++ b/docs/build_reference.ps1
@@ -0,0 +1,51 @@
+# This script uses `slangc` to generate stdlib reference documentation and push the updated
+# documents to shader-slang/stdlib-reference repository.
+# The stdlib-reference repository has github-pages setup so that the markdown files we generate
+# in this step will be rendered as html pages by Jekyll upon a commit to the repository.
+# So we we need to do here is to pull the stdlib-reference repository, regenerate the markdown files
+# and push the changes back to the repository.
+
+# The generated markdown files will be located in three folders:
+# - ./global-decls
+# - ./interfaces
+# - ./types
+# In addition, slangc will generate a table of content file `toc.html` which will be copied to
+# ./_includes/stdlib-reference-toc.html for Jekyll for consume it correctly.
+
+# If stdlib-reference folder does not exist, clone from github repo
+if (-not (Test-Path ".\stdlib-reference")) {
+    git clone https://github.com/shader-slang/stdlib-reference/
+}
+else {
+# If it already exist, just pull the latest changes.
+    cd stdlib-reference
+    git pull
+    cd ../
+}
+# Remove the old generated files.
+Remove-Item -Path ".\stdlib-reference\global-decls" -Recurse -Force
+Remove-Item -Path ".\stdlib-reference\interfaces" -Recurse -Force
+Remove-Item -Path ".\stdlib-reference\types" -Recurse -Force
+
+# Use git describe to produce a version string and write it to _includes/version.inc.
+# This file will be included by the stdlib-reference Jekyll template.
+git describe --tags | Out-File -FilePath ".\stdlib-reference\_includes\version.inc" -Encoding ASCII
+
+cd stdlib-reference
+& ../../build/Release/bin/slangc -compile-stdlib -doc
+Move-Item -Path ".\toc.html" -Destination ".\_includes\stdlib-reference-toc.html" -Force
+git config user.email "bot@shader-slang.com"
+git config user.name "Stdlib Reference Bot"
+git add .
+git commit -m "Update stdlib reference"
+git push
+cd ../
+
+# For local debugging only.
+# Remove-Item -Path "D:\git_repo\stdlib-reference\global-decls" -Recurse -Force
+# Remove-Item -Path "D:\git_repo\stdlib-reference\interfaces" -Recurse -Force
+# Remove-Item -Path "D:\git_repo\stdlib-reference\types" -Recurse -Force
+# Copy-Item -Path .\stdlib-reference\global-decls -Destination D:\git_repo\stdlib-reference\global-decls -Recurse -Force
+# Copy-Item -Path .\stdlib-reference\interfaces -Destination D:\git_repo\stdlib-reference\interfaces -Recurse -Force
+# Copy-Item -Path .\stdlib-reference\types -Destination D:\git_repo\stdlib-reference\types -Recurse -Force
+# Copy-Item -Path .\stdlib-reference\_includes\stdlib-reference-toc.html -Destination D:\git_repo\stdlib-reference\_includes\stdlib-reference-toc.html -Force
\ No newline at end of file
-- 
cgit v1.2.3