feat(monodocs): Add script for building docs for flytekit and flytectl

Signed-off-by: Chi-Sheng Liu <[email protected]>

Makefile

@@ -94,25 +94,20 @@ $(TMP_BUILD_DIR):
 	mkdir $@
 
 $(TMP_BUILD_DIR)/conda-lock-image: Dockerfile.conda-lock | $(TMP_BUILD_DIR)
-	docker buildx build --build-arg USER_UID=$$(id -u) --build-arg USER_GID=$$(id -g) -t flyte-conda-lock:latest -f Dockerfile.conda-lock .
+	docker buildx build --load --build-arg USER_UID=$$(id -u) --build-arg USER_GID=$$(id -g) -t flyte-conda-lock:latest -f Dockerfile.conda-lock .
 	touch $(TMP_BUILD_DIR)/conda-lock-image
 
 monodocs-environment.lock.yaml: monodocs-environment.yaml $(TMP_BUILD_DIR)/conda-lock-image
 	docker run --rm --pull never -v ./:/flyte flyte-conda-lock:latest lock --file monodocs-environment.yaml --lockfile monodocs-environment.lock.yaml --channel conda-forge
 
 $(TMP_BUILD_DIR)/dev-docs-image: Dockerfile.docs monodocs-environment.lock.yaml | $(TMP_BUILD_DIR)
-	docker buildx build --build-arg USER_UID=$$(id -u) --build-arg USER_GID=$$(id -g) -t flyte-dev-docs:latest -f Dockerfile.docs .
+	docker buildx build --load --build-arg USER_UID=$$(id -u) --build-arg USER_GID=$$(id -g) -t flyte-dev-docs:latest -f Dockerfile.docs .
 	touch $(TMP_BUILD_DIR)/dev-docs-image
 
 # Build docs in docker container for local development
-.PHONY: dev-docs-build
-dev-docs-build: $(TMP_BUILD_DIR)/dev-docs-image
-	docker run --rm --pull never -v ./docs:/docs flyte-dev-docs:latest sphinx-build -M html . _build
-
-# Build docs in docker container for local development with hot-reload
 .PHONY: dev-docs
 dev-docs: $(TMP_BUILD_DIR)/dev-docs-image
-	docker run --rm --pull never -p 8000:8000 -v ./docs:/docs flyte-dev-docs:latest sphinx-autobuild --host 0.0.0.0 --re-ignore '_build|_src|_tags|api|examples|flytectl|flytekit|flytesnacks|protos|tests' . ./_build/html
+	bash script/local_build_docs.sh
 
 .PHONY: help
 help: SHELL := /bin/sh

docs/community/contribute.rst

@@ -157,8 +157,8 @@ To build the Flyte docs locally you will need the following prerequisites:
 
 * Install `conda-lock <https://github.com/conda/conda-lock>`__.
 * In the ``flyteorg/flyte`` root directory you can run:
-    * ``make dev-docs-build`` to build the documentation locally. The build will be in the ``docs/_build/html`` directory.
-    * Alternatively, you can use ``make dev-docs`` to build the documentation with live reload. Open the browser to ``http://localhost:8000`` to see the documentation.
+    * ``make dev-docs`` to build the documentation locally. The build will be in the ``docs/_build/html`` directory. See `the script <https://github.com/flyteorg/flyte/blob/master/script/local_build_docs.sh>`__ for additional environment variables that can be set.
+        * For example, to use the local flytekit source code instead of the source code from the flyteorg/flytekit repo, run ``export FLYTEKIT_LOCAL_PATH=/path/to/flytekit`` before running ``make dev-docs``.
 
 ``flyteidl``
 ************

script/local_build_docs.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+set -eo pipefail
+
+# Available environment variables
+# - DEV_DOCS_WATCH: If set, the docs will be built and served using sphinx-autobuild for live updates
+# - FLYTEKIT_LOCAL_PATH: If set, the local path to flytekit will be used instead of the source code from the flyteorg/flytekit repo
+# - FLYTECTL_LOCAL_PATH: If set, the local path to flytectl will be used instead of the source code from the flyteorg/flytectl repo
+#
+# Example usages:
+#   ./script/local_build_docs.sh
+#   DEV_DOCS_WATCH=1 ./script/local_build_docs.sh
+#   FLYTEKIT_LOCAL_PATH=$(realpath ../flytekit) ./script/local_build_docs.sh
+
+DOCKER_ENV=()
+DOCKER_VOLUME_MAPPING=("-v" "./docs:/docs")
+DOCKER_PORT_MAPPING=()
+BUILD_CMD=("sphinx-build" "-M" "html" "." "_build")
+
+if [ -n "$DEV_DOCS_WATCH" ]; then
+  DOCKER_PORT_MAPPING+=("-p" "8000:8000")
+  BUILD_CMD=("sphinx-autobuild" "--host" "0.0.0.0" "--re-ignore" "'_build|_src|_tags|api|examples|flytectl|flytekit|flytesnacks|protos|tests'" "." "_build/html")
+fi
+
+if [ -n "$FLYTEKIT_LOCAL_PATH" ]; then
+  DOCKER_VOLUME_MAPPING+=("-v" "$FLYTEKIT_LOCAL_PATH:/flytekit")
+  DOCKER_ENV+=("--env" "FLYTEKIT_LOCAL_PATH=/flytekit")
+fi
+
+if [ -n "$FLYTECTL_LOCAL_PATH" ]; then
+  DOCKER_VOLUME_MAPPING+=("-v" "$FLYTECTL_LOCAL_PATH:/flytectl")
+  DOCKER_ENV+=("--env" "FLYTECTL_LOCAL_PATH=/flytectl")
+fi
+
+DOCKER_CMD=("docker" "run" "--rm" "--pull" "never" "${DOCKER_ENV[@]}" "${DOCKER_PORT_MAPPING[@]}" "${DOCKER_VOLUME_MAPPING[@]}" "flyte-dev-docs:latest" "${BUILD_CMD[@]}")
+
+echo "${DOCKER_CMD[*]}"
+
+"${DOCKER_CMD[@]}"