make docs to preview documentation locally (#366)

I had some updates to the documentation I wanted to make, but I wanted
to be able to preview the whole documentation set created by `cargo doc`
and `mdbook` in the the same directory structure as we have it hosted on
Github pages.

Also, I saw #363.

So with some extra components in our build image, and a combination of
`cargo watch` and a python dev library that hosts the files, and hot
reloads on changes for all documentation, we have a nice local tool for
writing and previewing documentation locally!

Closes #365

build/Makefile

@@ -101,6 +101,17 @@ build-image:
 	docker build -t $(IMAGE_NAME):$(package_version)-debug --build-arg PROFILE=debug -f $(project_path)/image/Dockerfile $(project_path)
 	docker build -t $(IMAGE_NAME):$(package_version) --build-arg PROFILE=release -f $(project_path)/image/Dockerfile $(project_path)
 
+# Runs mdbook and cargo doc in the same directory structure as what is hosted on Github pages.
+# Open http://localhost:3000/book/index.html or http://localhost:3000/api/quilkin/index.html after running. Pages will live reload on change.
+# (the .html extension is required for hot reload, but pages will display without it)
+docs: ensure-build-image
+	@echo "📭 Open browser to http://localhost:3000/book/index.html or http://localhost:3000/api/quilkin/index.html (the .html extension is required for hot reload)"
+	docker run -it --rm $(common_rust_args) -p 3000:3000 \
+		--entrypoint=bash $(BUILD_IMAGE_TAG) -c \
+		 	'mkdir /tmp/docs && (live-server -p 3000 /tmp/docs &) && \
+			mkdir -p ./target/doc; ln -s $$(pwd)/target/doc /tmp/docs/api && \
+			cargo watch -s "cargo doc --workspace --no-deps && cd docs && mdbook build --dest-dir /tmp/docs/book"'
+
 # Start an interactive shell inside the build image
 # Useful for testing, or adhoc cargo commands
 shell: ensure-build-image

build/build-image/Dockerfile

@@ -19,18 +19,21 @@ ARG RUST_TOOLCHAIN
 ENV RUSTUP_HOME=/usr/local/rustup \
     CARGO_HOME=/usr/local/cargo \
     PATH=/usr/local/cargo/bin:$PATH \
-    CROSS_DOCKER_IN_DOCKER=true
+    CROSS_DOCKER_IN_DOCKER=true \
+    LC_ALL=C.UTF-8 \
+    LANG=C.UTF-8
 
 RUN set -eux && \
     apt-get update && \
-    apt-get install -y wget zip build-essential libssl-dev pkg-config && \
+    apt-get install -y wget zip build-essential libssl-dev pkg-config python3-pip && \
+    pip3 install live-server && \
     wget https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init && \
     chmod +x rustup-init && \
     ./rustup-init -y --no-modify-path --default-toolchain $RUST_TOOLCHAIN && \
     rm rustup-init && \
     chmod -R a+w $RUSTUP_HOME $CARGO_HOME && \
     rustup component add rustfmt clippy && \
-    cargo install cross && \
+    cargo install cross cargo-watch mdbook && \
     cargo install cargo-about && \
     cargo install --locked cargo-deny && \
     rustup --version && \