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