diff --git a/Makefile b/Makefile index 2f44087959f..72dcadc5c3d 100644 --- a/Makefile +++ b/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 diff --git a/docs/community/contribute.rst b/docs/community/contribute.rst index cce5f7f6d6e..665cd10900a 100644 --- a/docs/community/contribute.rst +++ b/docs/community/contribute.rst @@ -157,8 +157,8 @@ To build the Flyte docs locally you will need the following prerequisites: * Install `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 `__ 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`` ************ diff --git a/script/local_build_docs.sh b/script/local_build_docs.sh new file mode 100755 index 00000000000..ebff0fa3ddc --- /dev/null +++ b/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[@]}"