From 137123294a669afbf163ae919df0a263b3397f1b Mon Sep 17 00:00:00 2001
From: Georgi Matev <georgi.matev@gmail.com>
Date: Thu, 1 Sep 2022 14:50:09 -0400
Subject: [PATCH] Auto-generate CLI docs in docs dev tooling (#721)

## Description

Auto-generate CLI docs in docs dev tooling.
* Add new Makefile target to rebuild the `mdgen` binary, only if needed. This helps with slow in container builds. Relies on host caching of both modules and the actual binary. This approach is probably not suitable for the actual docs CI build.
* Actual generation is fast and done every time when using relevant docs dev tooling commands.

NOTE: .gitignore may need to be adjusted if we switch to creating the CLI docs as part of build and tooling as opposed to the current automated PR with changes.

## Type of change

Please check the type of change your PR introduces:
- [x] :sunflower: Feature
- [ ] :bug: Bugfix
- [x] :world_map: Documentation
- [ ] :robot: Test
- [ ] :hamster: Trivial/Minor

## Issue(s)

## Test Plan

<!-- How will this be tested prior to merging.-->

- [x] :muscle: Manual
- [ ] :zap: Unit test
- [ ] :green_heart: E2E
---
 docs/Makefile  | 43 ++++++++++++++++++++++++++++++++++++++-----
 docs/README.md |  9 +++++++++
 2 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 3f658b555..eb03fe4c6 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,22 +1,36 @@
-.PHONY: buildimage build dev shell check
+.PHONY: buildimage build dev shell check genclidocs
+
+# 
+CORSO_BUILD_DIR := /tmp/.corsobuild
+CORSO_BUILD_CACHE := ${CORSO_BUILD_DIR}/cache
+CORSO_BUILD_MOD := ${CORSO_BUILD_DIR}/mod
+CORSO_BUILD_BIN := ${CORSO_BUILD_DIR}/bin
+
+CORSO_REPO := ${PWD}/..
+CORSO_REPO_CONTAINER := /go/src/github.com/alcionai/corso
+
+MDGEN_SRC_CONTAINER := ${CORSO_REPO_CONTAINER}/src/cmd/mdgen/mdgen.go
+MDGEN_BINARY := ${CORSO_BUILD_BIN}/mdgen
+CLI_DOCS_CONTAINER := ${CORSO_REPO_CONTAINER}/docs/docs/cli
+
 
 buildimage:
 	docker build -t "alcion/docs:latest" .
 
-dev:
+dev: genclidocs
 	docker run --rm -it \
 		-p 3000:3000 \
 		-v ${PWD}:/usr/src/docs alcion/docs
 
 VALE_TARGET ?= docs README.md
 
-dockercheck:
+dockercheck: genclidocs
 	docker run --rm \
 		-v ${PWD}:/usr/src/docs alcion/docs vale $(VALE_TARGET)
 	docker run --rm \
 	 	-v ${PWD}:/usr/src/docs alcion/docs markdownlint '**/*.md' --ignore styles/ --ignore src/ --ignore node_modules/
 
-check:
+check: genclidocs
 	vale $(VALE_TARGET)
 	markdownlint '**/*.md' --ignore styles/ --ignore src/ --ignore node_modules/
 
@@ -25,6 +39,25 @@ shell:
 		-p 3000:3000 \
 		-v ${PWD}:/usr/src/docs alcion/docs /bin/bash
 
-build:
+build: genclidocs
 	docker run --rm \
 		-v ${PWD}:/usr/src/docs alcion/docs npm run build
+
+genclidocs: ${MDGEN_BINARY}
+	@echo 'Auto-generating Corso CLI docs...'
+	docker run --rm -it \
+		-v ${CORSO_REPO}:${CORSO_REPO_CONTAINER} -v ${CORSO_BUILD_DIR}:${CORSO_BUILD_DIR} \
+		--workdir ${CORSO_REPO_CONTAINER}/src \
+		--entrypoint ${MDGEN_BINARY} \
+		golang:1.18 \
+		--cli-folder ${CLI_DOCS_CONTAINER}
+
+${MDGEN_BINARY}: ${CORSO_REPO}/src/** ${CORSO_REPO}/src/**/*.go
+	@echo 'Re-building Corso CLI docs auto-gen tooling...'
+	docker run --rm -it \
+		-v ${CORSO_REPO}:${CORSO_REPO_CONTAINER} -v ${CORSO_BUILD_DIR}:${CORSO_BUILD_DIR} \
+		--env GOCACHE=${CORSO_BUILD_CACHE} --env GOMODCACHE=${CORSO_BUILD_MOD} --env GOTMPDIR=${CORSO_BUILD_DIR} \
+		--workdir ${CORSO_REPO_CONTAINER}/src \
+		--entrypoint /usr/local/go/bin/go \
+		golang:1.18 \
+		build -o ${MDGEN_BINARY} ${MDGEN_SRC_CONTAINER}
diff --git a/docs/README.md b/docs/README.md
index 7c475d388..cac8b4ce2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -24,6 +24,15 @@ make dev
 
 This command starts a local development server within the Docker container and will expose docs at [http://localhost:3000](http://localhost:3000).
 
+## Generating Corso CLI docs
+
+```bash
+make genclidocs
+```
+
+Corso's CLI documents are auto-generated. This command explicitly triggers generating these docs. This step will happen
+automatically for the other commands where this is relevant.
+
 ## Building static documentation
 
 ```bash