[Doc] added code to support showing command docs for each patch and master (#350)

Co-authored-by: Samiya Akhtar <[email protected]>

Author: dennisseah

docs/commands/data.json

@@ -99,7 +99,8 @@
         "description": "Removes previously launched instances of the dashboard",
         "defaultValue": false
       }
-    ]
+    ],
+    "markdown": "## Description\n\nThis command launches the Service Introspection Dashboard for your current\nconfiguration. It requires `docker` to be installed on your machine in order to\nwork.\n"
   },
   "deployment get": {
     "command": "get",
@@ -151,7 +152,8 @@
         "description": "Watch the deployments for a live view",
         "defaultValue": false
       }
-    ]
+    ],
+    "markdown": "## Description\n\nThis commands retrieves the list of deployments by service name, release\nenvironment, build ID, commit ID, or container image tag.\n"
   },
   "deployment onboard": {
     "command": "onboard",
@@ -201,7 +203,8 @@
         "description": "The Azure subscription id",
         "required": true
       }
-    ]
+    ],
+    "markdown": "## Description\n\nPrepare storage for the service introspection tool. This will create a storage\naccount if it does not already exist in your subscription in the given\n`resource-group`. The storage table will also be created in a newly created or\nin an existing storage account if it does not exist already. When the Azure Key\nVault argument is specified, a secret with Azure storage access key will be\ncreated. Otherwise, the storage access key will need to be specified in\nenvironment variables manually.\n\nSee\n[Prerequisites](https://github.com/CatalystCode/spk/blob/master/guides/service-introspection.md#prerequisites)\n"
   },
   "deployment validate": {
     "command": "validate",
@@ -364,7 +367,7 @@
         "required": true
       },
       {
-        "arg": "-d, --hld-repo-url <hld-repo-url>",
+        "arg": "-U, --hld-repo-url <hld-repo-url>",
         "description": "The high level definition (HLD) git repo url; falls back to azure_devops.org in spk config.",
         "required": true
       },
@@ -389,7 +392,7 @@
         "required": true
       },
       {
-        "arg": "--project <project>",
+        "arg": "-d, --devops-project <project>",
         "description": "Azure DevOps project name; falls back to azure_devops.project in spk config.",
         "required": true
       },
@@ -644,7 +647,7 @@
         "description": "Azure DevOps organization name; falls back to azure_devops.org in spk config"
       },
       {
-        "arg": "-p, --project <project>",
+        "arg": "-d, --devops-project <project>",
         "description": "Azure DevOps project name; falls back to azure_devops.project in spk config"
       },
       {

docs/commands/index.html

@@ -54,6 +54,21 @@
     <div class="content-left">
     <div class="title">SPK Commands</div>
     <div>
+      
+      <div class="moniker-picker2" data-bi-name="moniker-picker" style="width:90%;margin-left:4px">
+        <div class="dropdown has-margin-bottom-small">
+          <button id="btnSelectRelease" class="dropdown-trigger has-flex-justify-content-start is-full-width button is-small has-border has-inner-focus" aria-expanded="false" aria-controls="ax-3">
+            <span class="visually-hidden"><!---->Select Version<!----></span>
+            <span id="selectedRelease" class="has-text-overflow-ellipsis"></span>
+            <span class="dropdown-button-chevron" aria-hidden="true">
+              <span class="icon docon docon-chevron-down-light expanded-indicator"></span>
+            </span>
+          </button>
+          <ul id="ulReleases" class="dropdown-menu is-full-width is-vertically-scrollable" id="ax-3" aria-label="Azure CLI" style="left: 0px; max-height: 140px;">
+          </ul> 
+        </div>
+      </div>
+      
       <div class="control has-icons-left">
         <input id="commandfilter" role="combobox" maxlength="100" aria-autocomplete="list" autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false" id="ax-0" class="autocomplete-input input control has-icons-left is-small is-full-width" type="text" aria-expanded="false" aria-owns="ax-1-listbox" aria-activedescendant="" placeholder="Filter by command">
 

docs/commands/releases.txt

@@ -1,23 +1,82 @@
 var data = null;
 var filter = "";
 var converter = new showdown.Converter();
+var releases = ["master"];
+var version = "master";
+var sepVersion = "@";
 
 var template =
   '<p class="cmd-title">@@main-cmd@@</p><p class="cmd-description">@@cmd-description@@</p><p>&nbsp;</p><p>Options:</p>@@options@@<p>&nbsp;</p>';
 var optionTemplate =
   '<p>@@option@@</p><p class="cmd-description">@@description@@</p><div class="line-space"></div>';
+var relTemplate =
+  '<li><a class="preserve-view button is-small has-border-none has-inner-focus has-flex-justify-content-start is-full-width has-text-wrap is-text-left">@@value@@</a></li>';
 
 function sanitize(str) {
   return str.replace("<", "&lt;").replace(">", "&gt;");
 }
 
+function getExistingVersions() {
+  $.ajax({
+    url: "releases.txt",
+    success: function(result) {
+      result.split("\n").forEach(function(r) {
+        var rTrim = r.trim();
+        if (rTrim && releases.indexOf(rTrim) === -1) {
+          releases.push(rTrim);
+        }
+      });
+      releases.sort(function(a, b) {
+        return a > b ? -1 : 1;
+      });
+    },
+    async: false
+  });
+}
+
+function getVersion() {
+  if (window.location.hash) {
+    var val = window.location.hash.substring(1); // remove #
+    var idx = val.indexOf(sepVersion);
+    if (idx !== -1) {
+      ver = val.substring(0, idx).trim();
+      if (releases.indexOf(ver) !== -1) {
+        version = ver;
+        return;
+      }
+    }
+  }
+  version = "master";
+}
+
+function populateVersionList() {
+  var oSelect = $("#ulReleases");
+  oSelect.html(
+    releases.reduce((a, c) => {
+      return a + relTemplate.replace("@@value@@", c);
+    }, "")
+  );
+  oSelect.find("li").each(function(i, elm) {
+    $(elm).on("click", function(evt) {
+      evt.stopPropagation();
+      oSelect.css("display", "none");
+      var ver = $(this).text();
+      if (ver !== version) {
+        version = ver;
+        $("#selectedRelease").text(version);
+        loadCommands();
+      }
+    });
+  });
+}
+
 function showDetails(key) {
   if (!key) {
-    window.location.hash = "";
+    window.location.hash = "#" + version + sepVersion;
     $("#spk-details").html("");
     return;
   }
-  window.location.hash = key.replace(/\s/g, "_");
+  window.location.hash = version + sepVersion + key.replace(/\s/g, "_");
   var cmd = data[key];
   var valuesArray = cmd.command.split(/\s/);
   var values = "";
@@ -84,7 +143,12 @@ function populateListing() {
     );
   }
   if (window.location.hash) {
-    var key = window.location.hash.replace(/_/g, " ").substring(1); // remove #
+    var hashTag = window.location.hash.substring(1); // remove #
+    var idx = hashTag.indexOf(sepVersion);
+    if (idx !== -1) {
+      hashTag = hashTag.substring(idx + 1);
+    }
+    var key = hashTag.replace(/_/g, " ");
     if (cmdKeys.indexOf(key) !== -1) {
       showDetails(key);
     } else {
@@ -109,8 +173,9 @@ var subheaderItems = function() {
   });
 };
 
-$(function() {
-  $.getJSON("./data.json", function(json) {
+function loadCommands() {
+  var url = version === "master" ? "./data.json" : "./data" + version + ".json";
+  $.getJSON(url, function(json) {
     data = json;
     subheaderItems();
     populateListing();
@@ -123,4 +188,15 @@ $(function() {
       populateListing();
     });
   });
+}
+
+$(function() {
+  $("#btnSelectRelease").on("click", function() {
+    $("#ulReleases").css("display", "block");
+  });
+  getExistingVersions();
+  getVersion();
+  $("#selectedRelease").text(version);
+  populateVersionList();
+  loadCommands();
 });

docs/commands/spk.js

@@ -111,6 +111,7 @@ a:visited {
 }
 #commandfilter {
   width: 90% !important;
+  margin-left: 4px;
   margin-bottom: 8px;
 }
 .input-icon {
@@ -119,3 +120,7 @@ a:visited {
 .small-font {
   font-size: 0.875rem;
 }
+#releases {
+  margin-left: 4px !important;
+  width: 90% !important;
+}

docs/commands/styles/spk.css

@@ -27,4 +27,10 @@ yarn config set version-git-message "release: ${RELEASE_TYPE} bump to v%s"
 
 # Bump version following the specified release type format
 yarn version "--${RELEASE_TYPE}"
+
+# copy a version of the command docs
+VERSION=$(cat package.json | grep '"version"' | sed -En 's/  "version": "(.*)",/\1/p')
+echo "${VERSION}" >> docs/commands/releases.txt
+cp docs/commands/data.json "docs/commands/data${VERSION}.json"
+
 git push ${REMOTE} ${RELEASE_BRANCH}