Move pandoc outside of go command and page setup from deploy script

We now generate the markdown comment from `usage` command,
and call pandoc from a script to handle generating HTML.

.circleci/deploy-gh-pages.sh

@@ -32,11 +32,7 @@ else
 fi
 
 # copy over or recompile the new site
-cp -a "../docs/." .
-
-# move index and update links
-mv circleci.html index.html
-sed -i -- 's#<a href="circleci.html">#<a href="index.html">#g' *.html
+cp -a "../out/." .
 
 # stage any changes and new files
 git add -A

.circleci/generate-docs.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+
+set -e
+
+# generate markdown docs
+go run main.go usage
+
+# setup output dir
+mkdir -p out
+
+# pandoc markdown to html into out dir
+for f in docs/*.md;  do
+    pandoc "$f" -s -o "out/$(basename ${f%.md}.html)";
+done
+
+# move index and update links
+mv out/circleci.html out/index.html
+sed -i -- 's#<a href="circleci.html">#<a href="index.html">#g' out/*.html

.gitignore

@@ -4,4 +4,5 @@ circleci-cli
 coverage.txt
 dist/
 docs/
+out/
 .vscode

cmd/root.go

@@ -13,12 +13,15 @@ import (
 
 var defaultEndpoint = "https://circleci.com/graphql-unstable"
 
+// rootCmd is used internally and global to the package but not exported
+// therefore we can use it in other commands, like `usage`
+// it should be set once when Execute is first called
 var rootCmd *cobra.Command
 
 // Execute adds all child commands to rootCmd and
 // sets flags appropriately. This function is called
 // by main.main(). It only needs to happen once to
-// the RootCmd.
+// the rootCmd.
 func Execute() {
 	command := MakeCommands()
 	if err := command.Execute(); err != nil {

cmd/usage.go

@@ -1,10 +1,7 @@
 package cmd
 
 import (
-	"fmt"
-	"io/ioutil"
 	"os"
-	"os/exec"
 	"path"
 	"path/filepath"
 	"strings"
@@ -26,33 +23,13 @@ func newUsageCommand() *cobra.Command {
 
 var defaultDocsPath = "docs"
 
-// nolint: gosec
-func isCmdAvailable(name string) bool {
-	cmd := exec.Command("/bin/sh", "-c", "command", "-v", name)
-	if err := cmd.Run(); err != nil {
-		return false
-	}
-	return true
-}
-
 func usage(cmd *cobra.Command, args []string) error {
-	if !isCmdAvailable("pandoc") {
-		return errors.New(`
-Unable to execute pandoc, please install it before using this command:
-    https://pandoc.org/installing.html`)
-	}
-
-	tmpDir, err := ioutil.TempDir("", "circleci-cli-usage-")
-	if err != nil {
-		return err
-	}
-
 	docsPath := defaultDocsPath
 	if len(args) > 0 {
 		docsPath = args[0]
 	}
 
-	if err = os.MkdirAll(docsPath, 0700); err != nil {
+	if err := os.MkdirAll(docsPath, 0700); err != nil {
 		return errors.Wrap(err, "Could not create usage docs directory")
 	}
 
@@ -61,26 +38,10 @@ Unable to execute pandoc, please install it before using this command:
 		return err
 	}
 
-	// generate markdown in tmpDir
+	// generate markdown to out
 	emptyStr := func(s string) string { return "" }
-	err = doc.GenMarkdownTreeCustom(rootCmd, tmpDir, emptyStr, func(name string) string {
+	return doc.GenMarkdownTreeCustom(rootCmd, out, emptyStr, func(name string) string {
 		base := strings.TrimSuffix(name, path.Ext(name))
 		return base + ".html"
 	})
-	if err != nil {
-		return err
-	}
-
-	// pandoc markdown from tmpDir to html into docsPath
-	scriptfmt := "for f in %s/*.md; do pandoc \"$f\" -s -o \"%s/$(basename ${f%%.md}.html)\"; done"
-	script := fmt.Sprintf(scriptfmt, tmpDir, out)
-
-	// nolint: gosec
-	pandoc := exec.Command("/bin/sh", "-c", script)
-	err = pandoc.Run()
-	if err != nil {
-		return err
-	}
-
-	return os.RemoveAll(tmpDir)
 }