add docker development workflow (#3738)

* add docker development workflow

Signed-off-by: Carlos Santana <csantana23@gmail.com>

* adding pesky EOL

Signed-off-by: Carlos Santana <csantana23@gmail.com>

.github/workflows/knative-mkdocs.yaml

@@ -2,7 +2,7 @@ name: Publish MkDocs
 
 on:
   push:
-    branches: [ mkdocs ]
+    branches: [ web ]
 
 jobs:
   mkdocs:
@@ -15,7 +15,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v2
         with:
-          python-version: '3.9'
+          python-version: '3.8'
 
       - name: Setup Node.js
         uses: actions/setup-node@v2
@@ -30,12 +30,12 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install mkdocs mkdocs-macros-plugin mkdocs-exclude mike
-          npm install
+          pip install mkdocs-material mkdocs-exclude mkdocs-macros-plugin mkdocs-awesome-pages-plugin mkdocs-redirects
+          npm ci
 
       - name: Build docs
         run: |
-          ./hack/build-with-blog.sh 
+          ./hack/build.sh
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3

hack/docker/Dockerfile

@@ -1,2 +1,12 @@
 FROM squidfunk/mkdocs-material
-RUN pip install --no-cache-dir mkdocs-macros-plugin mkdocs-exclude mkdocs-awesome-pages-plugin
+
+RUN apk add --no-cache --update nodejs npm bash hugo
+
+WORKDIR /site
+COPY ./package*.json /site/
+COPY ./requirements.txt /site/
+
+# Python Dependencies
+RUN pip --no-cache-dir install -r requirements.txt
+# NodeJS Dependencies
+RUN npm ci

hack/docker/README.md

@@ -1,19 +1,29 @@
 # Development notes for working with mkdocs
 
-## Container
+You can use a Docker container and run MkDocs from the container, so no local installation of mkdocs is required:
 
-Build the container image
-```bash
-./hack/docker/build.sh
-```
+- You need to have [Docker](https://www.docker.com) installed and running on your system
+- There are helper configurations installed if you have npm from [Node.JS](https://nodejs.org) installed.
+- Build the development docker container image, this is only need it once if the dependencies have not changed.
+    ```bash
+    npm run dev:build
+    ```
+- To start developing run command the following command in the root directory of the git repo (where **package.json** and **mkdocs.yaml** are located)
+    ```bash
+    npm run dev
+    ```
+- Open a browser to http://localhost:8000, where you will see the documentation site.  This will live update as you save changes to the Markdown files in the `docs` directory.
+- To stop developing run the following command in another terminal window, which will terminate the docker container
+    ```bash
+    npm run dev:stop
+    ```
+- To build the static HTML files including both mkdocs and hugo run the following command.
+    ```bash
+    npm test
+    ```
+- To view additional npm scripts run the following command
+    ```bash
+    npm run
+    ```
 
-Run the livereload site
-```bash
-./hack/docker/run.sh
-```
-
-Remove the container
-```bash
-./hack/docker/clean.sh
-```
 

hack/docker/build.sh

@@ -1,8 +1,10 @@
-#!/usr/bin/env bash
+#!/usr/bin/env sh
 
-IMAGE=${1:-mkdocs}
+set -x
+
+IMAGE=${1:-knative-docs-dev}
 
 SCRIPT_DIR=$(cd $(dirname $0); pwd -P)
-ROOT_DIR=$(cd "${SCRIPT_DIR}/.."; pwd -P)
+ROOT_DIR=$(cd "${SCRIPT_DIR}/../.."; pwd -P)
 
-docker build -t ${IMAGE} ${SCRIPT_DIR}
+docker build -t ${IMAGE} -f ${SCRIPT_DIR}/Dockerfile ${ROOT_DIR}

hack/docker/clean.sh

@@ -1,6 +1,6 @@
-#!/usr/bin/env bash
+#!/usr/bin/env sh
 
-NAME=${1:-mkdocs}
+NAME=${1:-knative-docs-dev}
 
 echo "Cleaning up old container '${NAME}'..."
 docker rm "${NAME}" --force 1> /dev/null 2> /dev/null

hack/docker/logs.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+
+set -x
+
+NAME=${1:-knative-docs-dev}
+docker logs -f ${NAME}

hack/docker/run.sh

@@ -1,10 +1,12 @@
-#!/usr/bin/env bash
+#!/usr/bin/env sh
 
-NAME=${1:-mkdocs}
+set -x
+
+NAME=${1:-knative-docs-dev}
 PORT=${2:-8000}
-IMAGE=${3:-mkdocs}
+IMAGE=${3:-knative-docs-dev}
 
-docker run --name "${NAME}" -d -p "${PORT}:${PORT}" -v "${PWD}:/site" mkdocs serve -f /site/mkdocs.yml --dirtyreload -a "0.0.0.0:${PORT}"
+docker run --name "${NAME}" -d -p "${PORT}:8000" -v "${PWD}:/site" ${IMAGE} serve --dirtyreload --dev-addr=0.0.0.0:8000
 echo "Dev environment running with live reloading enabled. Open http://localhost:${PORT} to see the site"
 echo "For live logs run:"
 echo "docker logs -f ${NAME}"

hack/docker/test.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+
+set -x
+
+NAME=${1:-knative-docs-dev}
+PORT=${2:-8000}
+IMAGE=${3:-knative-docs-dev}
+
+docker run --rm -v "${PWD}:/site" -it --entrypoint "" ${IMAGE} hack/build.sh

netlify.toml

@@ -1,7 +1,7 @@
 # Settings in the [build] context are global and are applied to all contexts
 # unless otherwise overridden by more specific contexts.
 [build]
-  command = "./hack/build-with-blog.sh"
+  command = "./hack/build.sh"
   publish = "site"
 
 [build.environment]

package.json

@@ -9,7 +9,13 @@
     "postcss-cli": "^8.3.1"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "predev":     "./hack/docker/clean.sh knative-docs-dev",
+    "dev":        "./hack/docker/run.sh knative-docs-dev 8000",
+    "postdev":    "./hack/docker/logs.sh knative-docs-dev",
+    "dev:stop":   "./hack/docker/clean.sh knative-docs-dev",
+    "dev:build":  "./hack/docker/build.sh knative-docs-dev",
+    "serve":      "./hack/mkdocs.sh",
+    "test":       "./hack/docker/test.sh && exit 1"
   },
   "repository": {
     "type": "git",