From 4f83d48b28b417a16d7caa834a9248b1bd50cdb8 Mon Sep 17 00:00:00 2001 From: Yong He Date: Sat, 24 Apr 2021 00:19:32 -0700 Subject: Auto generate interactive table of contents for user-guide. (#1818) --- docs/user-guide/build_toc.ps1 | 9 ++ docs/user-guide/index.md | 2 +- docs/user-guide/scripts/Program.cs | 164 ++++++++++++++++++++++++++++++++++++ docs/user-guide/user-guide-toc.html | 87 +++++++++++++++++++ 4 files changed, 261 insertions(+), 1 deletion(-) create mode 100644 docs/user-guide/build_toc.ps1 create mode 100644 docs/user-guide/scripts/Program.cs create mode 100644 docs/user-guide/user-guide-toc.html (limited to 'docs/user-guide') 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 fileNamePrefix = new List(); + public string title; + public string fileID; + public List sections = new List(); + public List children = new List(); + } + + public static void buildTOC(StringBuilder sb, Node n) + { + sb.AppendFormat("
  • {1}\n", n.fileID, n.title); + if (n.children.Count != 0) + { + sb.AppendLine("
      "); + foreach(var c in n.children) + buildTOC(sb, c); + sb.AppendLine("
    "); + } + else if (n.sections.Count != 0) + { + sb.AppendLine("
      "); + foreach (var s in n.sections) + { + sb.AppendFormat("
    • {2}
      • \n", n.fileID, getAnchorId(s), s); + } + sb.AppendLine("
    "); + } + sb.AppendLine("
    • "); + } + public static string buildTOC(Node n) + { + StringBuilder sb = new StringBuilder(); + sb.Append(@"
      "); + buildTOC(sb, n); + sb.Append(@"
    "); + 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 nodes = new List(); + 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 @@ +
    • Slang User's Guide +
        +
      • Introduction +
          +
        • Why use Slang?
          • +
        • Who is Slang for?
          • +
        • Who is this guide for?
          • +
        • Goals and Non-Goals
          • +
        +
        • +
      • Getting Started with Slang +
          +
        • Installation
          • +
        • Your first Slang shader
          • +
        • The full example
          • +
        +
        • +
      • Conventional Language Features +
          +
        • Types
          • +
        • Expressions
          • +
        • Statements
          • +
        • Functions
          • +
        • Preprocessor
          • +
        • Attributes
          • +
        • Global Variables and Shader Parameters
          • +
        • Shader Entry Points
          • +
        +
        • +
      • Basic Convenience Features +
          +
        • Type Inference in Variable Definitions
          • +
        • Immutable Values
          • +
        • Member functions
          • +
        • Properties
          • +
        • Initializers
          • +
        • Operator Overloading
          • +
        • `struct` inheritance (limited)
          • +
        • Extensions
          • +
        • Modules
          • +
        +
        • +
      • Interfaces and Generics +
          +
        • Interfaces
          • +
        • Generics
          • +
        • Supported Constructs in Interface Definitions
          • +
        • Associated Types
          • +
        • Generic Value Parameters
          • +
        • Interface-typed Values
          • +
        • Extending a Type with Additional Interface Conformances
          • +
        • Extensions to Interfaces
          • +
        +
        • +
      • Compiling Code with Slang +
          +
        • Concepts
          • +
        • Command-Line Compilation with `slangc`
          • +
        • Using the Compilation API
          • +
        +
        • +
      • Suported Compilation Targets +
          +
        • Background and Terminology
          • +
        • Direct3D 11
          • +
        • Direct3D 12
          • +
        • Vulkan
          • +
        • OpenGL
          • +
        • CUDA and OptiX
          • +
        • CPU Compute
          • +
        • Summary
          • +
        +
        • +
      • Special Topics +
          +
        • Handling Matrix Layout Differences on Different Platforms +
            +
          • Two conventions of matrix transform math
            • +
          • Overriding default matrix layout
            • +
          • Summary
            • +
          +
          • +
        +
        • +
      +
      • +
    \ No newline at end of file -- cgit v1.2.3