Generate CLI pages automatically

Author: wilzbach

ddoc_preprocessor.d

@@ -18,6 +18,8 @@ import std.algorithm, std.array, std.ascii, std.conv, std.file, std.format, std.
         std.meta, std.path, std.range, std.string, std.typecons;
 import std.stdio;
 
+import dmd.cli;
+
 struct Config
 {
     string dmdBinPath = "dmd";
@@ -51,6 +53,7 @@ All unknown options are passed to the compiler.
     // transform and extend the ddoc page
     text = genGrammar(text);
     text = genHeader(text);
+    text = genSwitches(text);
 
     // inject custom, "dynamic" macros
     text ~= "\nSRC_FILENAME=%s\n".format(inputFile.buildNormalizedPath);
@@ -72,15 +75,16 @@ auto compile(R)(R buffer, string[] arguments)
     return wait(pipes.pid);
 }
 
+enum indent = "    ";
+
 // replaces the content of a DDoc macro call
-auto updateDdocTag(string fileText, string ddocKey, string newContent)
+auto updateDdocTag(string fileText, string ddocKey, string content)
 {
+    auto newContent = ddocKey ~ "\n" ~ indent ~ content ~ ")";
     auto pos = fileText.representation.countUntil(ddocKey);
     if (pos < 0)
         return fileText;
 
-    newContent ~= ")";
-
     const ddocStartLength = ddocKey.representation.until('(', No.openRight).count;
     auto len = fileText[pos .. $].representation.drop(ddocStartLength).untilClosingParentheses.walkLength;
     return fileText.replace(fileText[pos .. pos + len + ddocStartLength + 1], newContent);
@@ -172,27 +176,26 @@ auto escapeDdoc(string s)
 auto genHeader(string fileText)
 {
     enum ddocKey = "$(HEADERNAV_TOC";
-    auto newContent = ddocKey ~ "\n";
-    enum indent = "    ";
+    string content;
     if (fileText.canFind(ddocKey))
     {
         foreach (entry; fileText.parseToc)
         {
             if (entry.children)
             {
-                newContent ~= "%s$(HEADERNAV_SUBITEMS %s, %s,\n".format(indent, entry.main.id, entry.main.name.escapeDdoc);
+                content ~= "%s$(HEADERNAV_SUBITEMS %s, %s,\n".format(indent, entry.main.id, entry.main.name.escapeDdoc);
                 foreach (child; entry.children)
-                    newContent ~= "%s$(HEADERNAV_ITEM %s, %s)\n".format(indent.repeat(2).joiner, child.id, child.name.escapeDdoc);
-                newContent ~= indent;
-                newContent ~= ")\n";
+                    content ~= "%s$(HEADERNAV_ITEM %s, %s)\n".format(indent.repeat(2).joiner, child.id, child.name.escapeDdoc);
+                content ~= indent;
+                content ~= ")\n";
             }
             else
             {
-                newContent ~= "%s$(HEADERNAV_ITEM %s, %s)\n".format(indent, entry.main.id, entry.main.name.escapeDdoc);
+                content ~= "%s$(HEADERNAV_ITEM %s, %s)\n".format(indent, entry.main.id, entry.main.name.escapeDdoc);
             }
         }
     }
-    return updateDdocTag(fileText, ddocKey, newContent);
+    return updateDdocTag(fileText, ddocKey, content);
 }
 
 // parse the menu from the Ddoc file
@@ -253,3 +256,92 @@ auto genGrammar(string fileText)
     return fileText;
 }
 
+// generate CLI documentation
+auto genSwitches(string fileText)
+{
+    enum ddocKey = "$(CLI_SWITCHES";
+    string content;
+    foreach (option; Usage.options)
+    {
+        string flag = option.flag;
+        string helpText = option.helpText;
+
+        // capitalize the first letter
+        helpText = helpText.capitalize.to!string;
+
+        highlightSpecialWords(flag, helpText);
+        auto flagEndPos = flag.representation.countUntil("=", "$(", "<");
+        string switchName;
+        if (flagEndPos < 0)
+            switchName = "$(SWNAME -%s)".format(flag);
+        else
+            switchName = "$(SWNAME -%s)%s".format(flag[0..flagEndPos], flag[flagEndPos..$]);
+
+        auto currentFlag = "$(SWITCH %s,\n
+            %s
+        )".format(switchName, helpText);
+
+        with(TargetOS)
+        switch(option.os)
+        {
+            case windows:
+                currentFlag = text("$(WINDOWS ", currentFlag, ")");
+                break;
+            case linux:
+            case macOS:
+            case freeBSD:
+            case solaris:
+            case dragonFlyBSD:
+                currentFlag = text("$(UNIX ", currentFlag, ")");
+                break;
+            case all:
+            default:
+                break;
+        }
+        content ~= currentFlag;
+    }
+    return updateDdocTag(fileText, ddocKey, content);
+}
+
+auto italic(string w)
+{
+    return "$(I %s )".format(w);
+}
+
+
+// capitalize the first letter
+auto capitalize(string w)
+{
+    import std.range, std.uni;
+    return w.take(1).asUpperCase.chain(w.dropOne);
+}
+
+private void highlightSpecialWords(ref string flag, ref string helpText)
+{
+    if (flag.canFind("<", "[") && flag.canFind(">", "]"))
+    {
+        string specialWord;
+
+        // detect special words in <...> and highlight them
+        static foreach (t; [["<", ">"], ["[", "]"]])
+        {
+            if (flag.canFind(t[0]))
+            {
+                specialWord = flag.findSplit(t[0])[2].until(t[1]).to!string;
+                // keep []
+                auto replaceWord = t[0] == "<" ? t[0] ~ specialWord ~ t[1] : specialWord;
+                flag = flag.replace(replaceWord, specialWord.italic);
+            }
+        }
+
+        // highlight individual words in the description
+        helpText = helpText
+            .splitter(" ")
+            .map!((w){
+                auto wPlain = w.filter!(c => !c.among('<', '>', '`', '\'')).to!string;
+                return wPlain == specialWord ? wPlain.italic: w;
+            })
+            .joiner(" ")
+            .to!string;
+    }
+}