Merge pull request #142 from backstage/automate-e2e

Create shell script automating the e2e instructions, update readme

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

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 $TECHDOCS_CONTAINER_DIR || 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'
+