From ffddecb766c2bb6a04308c5d1da2a874e9fd3ce8 Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Thu, 7 Sep 2023 14:49:18 +0200 Subject: [PATCH 1/2] create shell script automating the e2e instructions, update readme --- README.md | 39 ++++++++++++++++------------------ build-e2e-image.sh | 52 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 21 deletions(-) create mode 100755 build-e2e-image.sh diff --git a/README.md b/README.md index ef9f279..ab1b705 100644 --- a/README.md +++ b/README.md @@ -50,33 +50,30 @@ black . ### Testing Dependencies End-to-End -Much of the value of this plugin lies in its dependencies, on which there are -implicit dependencies upstream in the Backstage TechDocs frontend plugin. Each -time you update a pinned dependency, it's important to test that generated -documentation can be loaded and parsed as expected in the Backstage frontend. -The recommended way to do so is the following: - -1. Make the expected dependency change locally in `requirements.txt`. -2. Clone the [techdocs-container](https://github.com/backstage/techdocs-container) - image and, within the cloned directory, copy the entire contents of your - local version of `mkdocs-techdocs-core`, e.g. named `local-mkdocs-techdocs-core`. -3. Just before the `RUN pip install` command in `techdocs-container`'s - Dockerfile, add a `COPY` command that copies the contents of your modified - `mkdocs-techdocs-core` directory into the container's file system. Something - like: `COPY ./local-mkdocs-techdocs-core/ /local-mkdocs-techdocs-core/` -4. Modify the `RUN pip install`... command to install an editable version of - the copied local plugin, rather than the specific version. Something like... - `RUN pip install --upgrade pip && pip install -e /local-mkdocs-techdocs-core` -5. Build the modified image: `docker build -t mkdocs:local-dev .` -6. Modify your local Backstage instance to use your locally built - `techdocs-container` instead of using the published image by setting the - following configuration: +If you have made changes to the plugin itself, or updated a dependency it's +strongly recommended to test the plugin. + +To build a version of the `spotify/techdocs` docker image with your changes, +run the below script in this repository: +```bash +./build-e2e-image.sh +``` +_The script is only tested on OSX_ + +The script assumes that you have the +[image repository](https://github.com/backstage/techdocs-container) cloned in a +sibling directory to this repository (or you can specify its location). + +It will build an image called `mkdocs:local-dev` including the changes you +have made locally. To test the image in backstage, edit the config (e.g. +`app-config.yaml`) with the following: ```yaml techdocs: generator: runIn: "docker" dockerImage: "mkdocs:local-dev" + pullImage: false ``` ### Release diff --git a/build-e2e-image.sh b/build-e2e-image.sh new file mode 100755 index 0000000..6c92fb8 --- /dev/null +++ b/build-e2e-image.sh @@ -0,0 +1,52 @@ +#!/bin/sh + +PWD=$(pwd) +ASSUMED_TECHDOCS_CONTAINER_DIR="$(dirname "$PWD")/techdocs-container" + +echo "Enter the path to your local techdocs-image repository ($ASSUMED_TECHDOCS_CONTAINER_DIR): " + +read TECHDOCS_CONTAINER_DIR + +if [ ! "$TECHDOCS_CONTAINER_DIR" ]; then + echo "Using default $ASSUMED_TECHDOCS_CONTAINER_DIR" + TECHDOCS_CONTAINER_DIR=$ASSUMED_TECHDOCS_CONTAINER_DIR +fi + +# Check the dir for the expected catalog file +EXPECTED_CATALOG_CONTENT=$(grep -E "name: techdocs-container$" "${TECHDOCS_CONTAINER_DIR}/catalog-info.yaml") + +if [ ! "$EXPECTED_CATALOG_CONTENT" ]; then + echo "[ERROR] did not find expected content in ${TECHDOCS_CONTAINER_DIR}/catalog-info.yaml, please make sure the dir is correct and that the repo is cloned" + exit 1 +fi + +# From now on we assume the image repo is next to this one +DOCKERFILE="$TECHDOCS_CONTAINER_DIR/Dockerfile" + +# Remove and copy this repo to the techdocs container local repo +rm -rf "${TECHDOCS_CONTAINER_DIR}/local-mkdocs-techdocs-core" +cp -r $PWD "${TECHDOCS_CONTAINER_DIR}/local-mkdocs-techdocs-core" + +COPY_COMMAND="COPY .\/local-mkdocs-techdocs-core \/local-mkdocs-techdocs-core \n" + +# Remove any previously added COPY instruction +sed -i '' '/COPY .\/local-mkdocs-techdocs-core/d' $DOCKERFILE + +# Add the COPY instruction +sed -i '' "s/^\(RUN pip install.*\)/${COPY_COMMAND}\1/" $DOCKERFILE + +# Install the local version instead of the public release +sed -E -i '' "s/pip install mkdocs-techdocs-core==[0-9]+\.[0-9]+\.[0-9]+/pip install -e \/local-mkdocs-techdocs-core/" $DOCKERFILE + +# Build the image +docker build -f $DOCKERFILE -t mkdocs:local-dev . || exit 1 + +echo "================================================================================\n" +echo "The docker image is built, now use it in your config: \n" + +echo 'techdocs:' +echo ' generator:' +echo ' runIn: "docker"' +echo ' dockerImage: mkdocs:local-dev' +echo ' pullImage: false' + From 6e73c8779c933f0b97cd8a363a5d17d477239dab Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Fri, 8 Sep 2023 09:21:49 +0200 Subject: [PATCH 2/2] Update build-e2e-image.sh Co-authored-by: Sydney Achinger <78113809+squid-ney@users.noreply.github.com> --- build-e2e-image.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build-e2e-image.sh b/build-e2e-image.sh index 6c92fb8..c49b02d 100755 --- a/build-e2e-image.sh +++ b/build-e2e-image.sh @@ -39,7 +39,7 @@ sed -i '' "s/^\(RUN pip install.*\)/${COPY_COMMAND}\1/" $DOCKERFILE sed -E -i '' "s/pip install mkdocs-techdocs-core==[0-9]+\.[0-9]+\.[0-9]+/pip install -e \/local-mkdocs-techdocs-core/" $DOCKERFILE # Build the image -docker build -f $DOCKERFILE -t mkdocs:local-dev . || exit 1 +docker build -f $DOCKERFILE -t mkdocs:local-dev $TECHDOCS_CONTAINER_DIR || exit 1 echo "================================================================================\n" echo "The docker image is built, now use it in your config: \n"