Auto generate interactive table of contents for user-guide. (#1818)

4 files changed, 261 insertions, 1 deletions

diff --git a/docs/user-guide/build_toc.ps1 b/docs/user-guide/build_toc.ps1
new file mode 100644
index 000000000..15603c8cb
--- /dev/null
+++ b/docs/user-guide/build_toc.ps1
@@ -0,0 +1,9 @@
+$job = Start-Job -ArgumentList $PSScriptRoot -ScriptBlock {
+    Set-Location $args[0]
+    $code = (Get-Content -Raw -Path "scripts/Program.cs").ToString()
+    $assemblies = ("System.Core", "System.IO", "System.Collections")
+    Add-Type -ReferencedAssemblies $assemblies -TypeDefinition $code -Language CSharp	
+    [toc.Builder]::Run($args[0])
+}
+Wait-Job $job
+Receive-Job -Job $job
diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md
index 4d82fa8ec..9f5a36e86 100644
--- a/docs/user-guide/index.md
+++ b/docs/user-guide/index.md
@@ -3,7 +3,7 @@ layout: user-guide
 ---

 

 Slang User's Guide

-------------------

+=============

 

 Welcome to the Slang User's Guide, an introduction to the Slang language, compiler, and API. In this guide, you will learn:

 - Slang's language features, including those inherited from HLSL and additional language features to make it easy to work with shaders.

diff --git a/docs/user-guide/scripts/Program.cs b/docs/user-guide/scripts/Program.cs
new file mode 100644
index 000000000..4ed2d18a6
--- /dev/null
+++ b/docs/user-guide/scripts/Program.cs
@@ -0,0 +1,164 @@
+using System;
+using System.IO;
+using System.Text;
+using System.Collections.Generic;
+namespace toc
+{
+    public class Builder
+    {
+        public static string getAnchorId(string title)
+        {
+            StringBuilder sb = new StringBuilder();
+            title = title.Trim().ToLower();
+            foreach (var ch in title)
+            {
+                if (ch >= 'a' && ch <= 'z' || ch >= '0' && ch <= '9'
+                    || ch == '-')
+                    sb.Append(ch);
+                else if (ch==' ' || ch =='_')
+                    sb.Append('-');
+            }
+            return sb.ToString();
+        }
+
+        public class Node
+        {
+            public List<string> fileNamePrefix = new List<string>();
+            public string title;
+            public string fileID;
+            public List<string> sections = new List<string>();
+            public List<Node> children = new List<Node>();
+        }
+
+        public static void buildTOC(StringBuilder sb, Node n)
+        {
+            sb.AppendFormat("<li data-link=\"{0}\"><span>{1}</span>\n", n.fileID, n.title);
+            if (n.children.Count != 0)
+            {
+                sb.AppendLine("<ul class=\"toc_list\">");
+                foreach(var c in n.children)
+                    buildTOC(sb, c);
+                sb.AppendLine("</ul>");
+            }
+            else if (n.sections.Count != 0)
+            {
+                sb.AppendLine("<ul class=\"toc_list\">");
+                foreach (var s in n.sections)
+                {
+                    sb.AppendFormat("<li data-link=\"{0}#{1}\"><span>{2}</span></li>\n", n.fileID, getAnchorId(s), s);
+                }
+                sb.AppendLine("</ul>");
+            }
+            sb.AppendLine("</li>");
+        }
+        public static string buildTOC(Node n)
+        {
+            StringBuilder sb = new StringBuilder();
+            sb.Append(@"<ul class=""toc_root_list"">");
+            buildTOC(sb, n);
+            sb.Append(@"</ul>");
+            return sb.ToString();
+        }
+
+        public static bool isChild(Node parent, Node child)
+        {
+            if (parent.fileNamePrefix.Count < child.fileNamePrefix.Count)
+            {
+                bool equal = true;
+                for (int k = 0; k < parent.fileNamePrefix.Count; k++)
+                {
+                    if (parent.fileNamePrefix[k] != child.fileNamePrefix[k])
+                    {
+                        equal = false;
+                        break;
+                    }
+                }
+                return equal;
+            }
+            return false;
+        }
+        public static string Run(string path)
+        {
+            StringBuilder outputSB = new StringBuilder();
+            outputSB.AppendFormat("Building table of contents from {0}...\n", path);
+            var files = System.IO.Directory.EnumerateFiles(path, "*.md");
+            List<Node> nodes = new List<Node>();
+            foreach (var f in files)
+            {
+                var content = File.ReadAllLines(f);
+                Node node = new Node();
+                node.fileID = Path.GetFileNameWithoutExtension(f);
+                outputSB.AppendFormat("  {0}.md\n", node.fileID);
+                for (int i = 1; i < content.Length; i++)
+                {
+                    if (content[i-1].StartsWith("layout: "))
+                        continue;
+                    if (content[i].StartsWith("==="))
+                        node.title = content[i-1];
+                    if (content[i].StartsWith("---"))
+                        node.sections.Add(content[i-1]);
+                    if (content[i].StartsWith("#") && !content[i].StartsWith("##") && node.title == null)
+                        node.title = content[i].Substring(1, content[i].Length - 1).Trim();
+                    if (content[i].StartsWith("##") && !content[i].StartsWith("###"))
+                        node.sections.Add(content[i].Substring(2, content[i].Length - 2).Trim());
+                }
+                if (node.title == null)
+                {
+                    outputSB.AppendFormat("Error: {0} does not define a title.", f);
+                    node.title = "Untitiled";
+                }
+                var titleSecs = Path.GetFileName(f).Split('-');
+                foreach (var s in titleSecs)
+                {
+                    if (s.Length == 2 && s[1]>='0' && s[1] <= '9')
+                    {
+                        node.fileNamePrefix.Add(s);
+                    }
+                    else
+                    {
+                        break;
+                    }
+                }
+                // Find parent node.
+                Node parent=null;
+                for (int l = nodes.Count-1; l>=0; l--)
+                {
+                    var n = nodes[l];
+                    if (isChild(n, node))
+                    {
+                       parent = n;
+                       break;
+                    }
+                }
+                if (parent != null)
+                    parent.children.Add(node);
+                else
+                {
+                    // find child
+                    foreach (var other in nodes)
+                    {
+                        if (isChild(node, other))
+                        {
+                            node.children.Add(other);
+                        }
+                    }
+                    foreach (var c in node.children)
+                    {
+                        nodes.Remove(c);
+
+                    }
+                    nodes.Add(node);
+                }
+            }
+            var root = nodes.Find(x=>x.fileID=="index");
+            if (root != null)
+            {
+                var html = buildTOC(root);
+                var outPath = Path.Combine(path, "user-guide-toc.html");
+                File.WriteAllText(outPath, html);
+                outputSB.AppendFormat("Output written to: {0}\n", outPath);
+            }
+            return outputSB.ToString();
+        }
+    }
+}
\ No newline at end of file
diff --git a/docs/user-guide/user-guide-toc.html b/docs/user-guide/user-guide-toc.html
new file mode 100644
index 000000000..0847fcc3e
--- /dev/null
+++ b/docs/user-guide/user-guide-toc.html
@@ -0,0 +1,87 @@
+<ul class="toc_root_list"><li data-link="index"><span>Slang User's Guide</span>
+<ul class="toc_list">
+<li data-link="00-introduction"><span>Introduction</span>
+<ul class="toc_list">
+<li data-link="00-introduction#why-use-slang"><span>Why use Slang?</span></li>
+<li data-link="00-introduction#who-is-slang-for"><span>Who is Slang for?</span></li>
+<li data-link="00-introduction#who-is-this-guide-for"><span>Who is this guide for?</span></li>
+<li data-link="00-introduction#goals-and-non-goals"><span>Goals and Non-Goals</span></li>
+</ul>
+</li>
+<li data-link="01-get-started"><span>Getting Started with Slang</span>
+<ul class="toc_list">
+<li data-link="01-get-started#installation"><span>Installation</span></li>
+<li data-link="01-get-started#your-first-slang-shader"><span>Your first Slang shader</span></li>
+<li data-link="01-get-started#the-full-example"><span>The full example</span></li>
+</ul>
+</li>
+<li data-link="02-conventional-features"><span>Conventional Language Features</span>
+<ul class="toc_list">
+<li data-link="02-conventional-features#types"><span>Types</span></li>
+<li data-link="02-conventional-features#expressions"><span>Expressions</span></li>
+<li data-link="02-conventional-features#statements"><span>Statements</span></li>
+<li data-link="02-conventional-features#functions"><span>Functions</span></li>
+<li data-link="02-conventional-features#preprocessor"><span>Preprocessor</span></li>
+<li data-link="02-conventional-features#attributes"><span>Attributes</span></li>
+<li data-link="02-conventional-features#global-variables-and-shader-parameters"><span>Global Variables and Shader Parameters</span></li>
+<li data-link="02-conventional-features#shader-entry-points"><span>Shader Entry Points</span></li>
+</ul>
+</li>
+<li data-link="03-convenience-features"><span>Basic Convenience Features</span>
+<ul class="toc_list">
+<li data-link="03-convenience-features#type-inference-in-variable-definitions"><span>Type Inference in Variable Definitions</span></li>
+<li data-link="03-convenience-features#immutable-values"><span>Immutable Values</span></li>
+<li data-link="03-convenience-features#member-functions"><span>Member functions</span></li>
+<li data-link="03-convenience-features#properties"><span>Properties</span></li>
+<li data-link="03-convenience-features#initializers"><span>Initializers</span></li>
+<li data-link="03-convenience-features#operator-overloading"><span>Operator Overloading</span></li>
+<li data-link="03-convenience-features#struct-inheritance-limited"><span>`struct` inheritance (limited)</span></li>
+<li data-link="03-convenience-features#extensions"><span>Extensions</span></li>
+<li data-link="03-convenience-features#modules"><span>Modules</span></li>
+</ul>
+</li>
+<li data-link="04-interfaces-generics"><span>Interfaces and Generics</span>
+<ul class="toc_list">
+<li data-link="04-interfaces-generics#interfaces"><span>Interfaces</span></li>
+<li data-link="04-interfaces-generics#generics"><span>Generics</span></li>
+<li data-link="04-interfaces-generics#supported-constructs-in-interface-definitions"><span>Supported Constructs in Interface Definitions</span></li>
+<li data-link="04-interfaces-generics#associated-types"><span>Associated Types</span></li>
+<li data-link="04-interfaces-generics#generic-value-parameters"><span>Generic Value Parameters</span></li>
+<li data-link="04-interfaces-generics#interface-typed-values"><span>Interface-typed Values</span></li>
+<li data-link="04-interfaces-generics#extending-a-type-with-additional-interface-conformances"><span>Extending a Type with Additional Interface Conformances</span></li>
+<li data-link="04-interfaces-generics#extensions-to-interfaces"><span>Extensions to Interfaces</span></li>
+</ul>
+</li>
+<li data-link="05-compiling"><span>Compiling Code with Slang</span>
+<ul class="toc_list">
+<li data-link="05-compiling#concepts"><span>Concepts</span></li>
+<li data-link="05-compiling#command-line-compilation-with-slangc"><span>Command-Line Compilation with `slangc`</span></li>
+<li data-link="05-compiling#using-the-compilation-api"><span>Using the Compilation API</span></li>
+</ul>
+</li>
+<li data-link="06-targets"><span>Suported Compilation Targets</span>
+<ul class="toc_list">
+<li data-link="06-targets#background-and-terminology"><span>Background and Terminology</span></li>
+<li data-link="06-targets#direct3d-11"><span>Direct3D 11</span></li>
+<li data-link="06-targets#direct3d-12"><span>Direct3D 12</span></li>
+<li data-link="06-targets#vulkan"><span>Vulkan</span></li>
+<li data-link="06-targets#opengl"><span>OpenGL</span></li>
+<li data-link="06-targets#cuda-and-optix"><span>CUDA and OptiX</span></li>
+<li data-link="06-targets#cpu-compute"><span>CPU Compute</span></li>
+<li data-link="06-targets#summary"><span>Summary</span></li>
+</ul>
+</li>
+<li data-link="a1-special-topics"><span>Special Topics</span>
+<ul class="toc_list">
+<li data-link="a1-01-matrix-layout"><span>Handling Matrix Layout Differences on Different Platforms</span>
+<ul class="toc_list">
+<li data-link="a1-01-matrix-layout#two-conventions-of-matrix-transform-math"><span>Two conventions of matrix transform math</span></li>
+<li data-link="a1-01-matrix-layout#overriding-default-matrix-layout"><span>Overriding default matrix layout</span></li>
+<li data-link="a1-01-matrix-layout#summary"><span>Summary</span></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
\ No newline at end of file